VMap

<VMap> is the only stateful boot component. It loads the MapKit JS runtime from Apple's CDN, initializes it with your token, creates the mapkit.Map, and provides the instance to every child via Vue's provide/inject. Annotations, overlays, and controls must be nested inside it.

Usage

<script setup lang="ts">
  import { VMap, VMarkerAnnotation } from '@geoql/v-mapkit';

  const token = 'YOUR_MAPKIT_TOKEN';

  function onMap(map: mapkit.Map) {
    map.setRegionAnimated(
      new mapkit.CoordinateRegion(
        new mapkit.Coordinate(37.3349, -122.009),
        new mapkit.CoordinateSpan(0.06, 0.06),
      ),
    );
  }
</script>

<template>
  <VMap :access-token="token" color-scheme="light" @map="onMap">
    <VMarkerAnnotation :coordinates="[37.3349, -122.009]" />
  </VMap>
</template>

Props

access-token

• Type: string
• Required: true

The MapKit JS token (JWT) used to authorize the runtime. See Getting Started for how to obtain one.

Core options

Configuration props

colorScheme, distances, padding, tintColor, pointOfInterestFilter, showsPointsOfInterest, cameraBoundary, cameraDistance, cameraZoomRange, selectableMapFeatures, and the control toggles (showsCompass, showsZoomControl, showsScale, showsMapTypeControl, showsUserLocationControl, showsUserLocation, tracksUserLocation) are all reactive. See the Configuration guide for the full table.

cluster-annotation

• Type: (cluster: mapkit.Annotation) => mapkit.Annotation

A factory that renders grouped annotations. See Clustering.

Events

@map

Emitted once the mapkit.Map instance is created and ready. This is where you set the initial region, since coordinates are not props.

• Payload: mapkit.Map

Lifecycle events

Map interaction events

<VMap> forwards MapKit's map events as kebab-cased Vue events:

<VMap
  :access-token="token"
  @region-change-start="onRegionStart"
  @region-change-end="onRegionEnd"
  @zoom-start="onZoomStart"
  @zoom-end="onZoomEnd"
  @scroll-start="onScrollStart"
  @scroll-end="onScrollEnd"
  @rotation-start="onRotationStart"
  @rotation-end="onRotationEnd"
  @single-tap="onSingleTap"
  @double-tap="onDoubleTap"
  @long-press="onLongPress"
  @select="onSelect"
  @deselect="onDeselect"
  @user-location-change="onUserLocation"
/>

Available: @region-change-start, @region-change-end, @rotation-start, @rotation-end, @scroll-start, @scroll-end, @zoom-start, @zoom-end, @map-type-change, @select, @deselect, @drag-start, @dragging, @drag-end, @user-location-change, @user-location-error, @single-tap, @double-tap, @long-press.

Slots

default

Nest child components — annotations, overlays, and controls. The slot is bound with { ready, map } for advanced cases.

<VMap :access-token="token" v-slot="{ ready }">
  <VMarkerAnnotation v-if="ready" :coordinates="[37.3349, -122.009]" />
</VMap>

Accessing the Map Instance

Child components read the shared map through injection keys — never via props. VMap provides three:

<script setup lang="ts">
  import { inject } from 'vue';
  import type { Ref } from 'vue';
  import {
    MapKitGlobalKey,
    MapKitInstanceKey,
    MapKitReadyKey,
  } from '@geoql/v-mapkit';

  const mk = inject<Ref<typeof mapkit | undefined>>(MapKitGlobalKey);
  const map = inject<Ref<mapkit.Map | undefined>>(MapKitInstanceKey);
  const ready = inject<Ref<boolean>>(MapKitReadyKey);
</script>

For building your own children, the useMapChild composable encodes the create/update/remove lifecycle.

Multiple Maps

Each <VMap> provides its own scoped instance, so children always resolve the nearest map. Multiple maps on one page are fully supported.

<template>
  <VMap :access-token="token" color-scheme="light" />
  <VMap :access-token="token" color-scheme="dark" />
</template>

TypeScript

Props are exported from the package types:

import type { VMapProps } from '@geoql/v-mapkit';