Methods & native access

Move the camera, fit markers, locate and access native controls.

3 min readVue 3 / Nuxt 4Live example included

On this page

Controls Integration Native APIs Nuxt and global registration Migrating from 1.x

Interactive exampleMapLibre

Vue 3 · TypeScript

<script setup lang="ts">
import { ref, shallowRef } from 'vue'
import { NeshanMapLibre, MAPLIBRE_STYLES, type Coordinates, type MapLibreMarker } from 'vue-neshan-maps'
import 'vue-neshan-maps/style.css'

const webKey = import.meta.env.VITE_NESHAN_WEB_KEY
const center = ref<Coordinates>([35.72, 51.36])
const zoom = ref(12.2)
const markers = shallowRef<MapLibreMarker[]>([
  {
    "id": "azadi",
    "position": [
      35.6997,
      51.338
    ],
    "popup": "Azadi Square",
    "tooltip": "Drag this marker",
    "options": {
      "draggable": true
    }
  },
  {
    "id": "milad",
    "position": [
      35.7448,
      51.3753
    ],
    "popup": "Milad Tower",
    "options": {
      "draggable": true
    }
  }
])
function saveMarker(marker: MapLibreMarker, position: Coordinates) {
  markers.value = markers.value.map(item => item.id === marker.id ? { ...item, position } : item)
}
const mapRef = ref<InstanceType<typeof NeshanMapLibre>>()
function fly() { mapRef.value?.flyTo([35.7448, 51.3753], 15) }
</script>

<template>
  <NeshanMapLibre
    v-model="center" v-model:zoom="zoom"
    :api-key="webKey"
    :styles="{ height: '420px' }"
    :center-marker="false"
    :map-style="MAPLIBRE_STYLES.light"
    :traffic="false" :poi="false"
    :markers="markers" @marker-dragend="saveMarker"
    ref="mapRef"
  />
  <button @click="fly">Milad Tower</button>
</template>

Set VITE_NESHAN_WEB_KEY in your ignored .env.local. This code reflects the controls above; your actual key is never included.

Controls#

Use a component ref, as in the complete example, for the public commands below. Disable controls until ready and clear readiness on destroy.

Task	Command / behavior
Show all markers	`fitToMarkers()` or reactive `fitMarkers`
Move to a place	`flyTo([latitude, longitude], zoom)`
Frame a region	`fitBounds(bounds, options)`; native engine coordinate order
Repair size after opening a hidden panel	`invalidateSize()`; normal resizing is automatic
Reinitialize	`retry()`; returns a promise
Request device location	`locate({ setView: true, maxZoom: 16 })`

locate should run after an explicit user action. It needs HTTPS/localhost and browser permission. Handle location-found and location-error; do not assume every device can provide a position. ready means initialization succeeded, not that every tile has been authorized.

Integration#

Native APIs#

Use useNeshanMapLibre to retain native refs; wire both lifecycle handlers. The component disposes of the map, while the composable clears its references. Native MapLibre calls use longitude first, unlike the component's public flyTo method.

vue

<script setup lang="ts">
import { NeshanMapLibre, useNeshanMapLibre } from 'vue-neshan-maps'
import 'vue-neshan-maps/style.css'
const webKey = import.meta.env.VITE_NESHAN_WEB_KEY
const { map, onReady, onDestroy } = useNeshanMapLibre()
function go() {
  // Native MapLibre coordinates are LONGITUDE first.
  map.value?.flyTo({ center: [51.338, 35.6997], zoom: 15 })
}
</script>
<template>
  <button :disabled="!map" @click="go">Azadi Square</button>
  <NeshanMapLibre :api-key="webKey" @ready="onReady" @destroy="onDestroy" />
</template>

For Leaflet, use useNeshanMap; ready contains { map, L }. MapLibre uses { map, maplibre }. Do not assume native APIs or plugins work across engines. Constructor-only options require remounting with a Vue :key when they change.

Nuxt and global registration#

Imports are SSR-safe; renderer initialization runs on mount. Import CSS globally in nuxt.config.ts; use a .client.vue component or optional <ClientOnly> when your surrounding integration requires it. Obtain the web key through public runtime config. Keep service keys in private server config.

export default defineNuxtConfig({
  css: ['vue-neshan-maps/style.css'],
  runtimeConfig: { public: { neshanWebKey: '' } },
})

Set NUXT_PUBLIC_NESHAN_WEB_KEY in your deployment environment. Nuxt and plugin examples show the component and registration code. Local imports are simplest; app.use(NeshanMapPlugin) registers both components globally when preferred.

Migrating from 1.x#

Version 2 targets Vue 3.5.43+ and requires an explicit CSS import. Vue is a peer dependency. Replace old UMD script usage with package imports. Leaflet options.key, options.center, latitude and longitude events remain supported; prefer apiKey and the two models for new code. Existing Leaflet markers/shape data remain useful, but native marker options need adaptation when switching engines. Old installations are not changed automatically.

Found something unclear?View the source Report an issue