Annotations

Annotations mark points on the map. Each is a child of <VMap>, takes a [lat, lng] tuple (or a MapKit Place/MapFeature), and is added, updated, and removed automatically with the component's lifecycle.

VMarkerAnnotation

MapKit's classic teardrop pin. Pass coordinates plus an optional annotation object for title, subtitle, color, and glyph.

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

<template>
  <VMap :access-token="token">
    <VMarkerAnnotation
      :coordinates="[37.7749, -122.4194]"
      :annotation="{
        title: 'San Francisco',
        subtitle: 'City Hall',
        color: '#0a84ff',
        glyphText: '★',
      }"
    />
  </VMap>
</template>

Prop	Type	Description
`coordinates`	`[number, number]`	`[latitude, longitude]` (required)
`annotation`	`mapkit.MarkerAnnotationConstructorOptions`	Title, subtitle, color, glyph, etc.
`clusteringIdentifier`	`string`	Group with other annotations — see Clustering

VImageAnnotation

Renders a custom image as the annotation marker instead of a pin.

<VMap :access-token="token">
  <VImageAnnotation
    :coordinates="[37.3349, -122.009]"
    :annotation="{
      title: 'Apple Park',
      url: { 1: '/pin.png', 2: '/pin@2x.png' },
      size: { width: 32, height: 32 },
    }"
  />
</VMap>

Prop	Type	Description
`coordinates`	`[number, number]`	`[latitude, longitude]` (required)
`annotation`	`mapkit.ImageAnnotationConstructorOptions`	Image URLs, size, anchor (required)
`clusteringIdentifier`	`string`	Group with other annotations

VPlaceAnnotation

Renders an annotation from a MapKit Place — the result objects returned by search and geocoding.

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

  const { geocode } = useGeocoder();
  const place = shallowRef<mapkit.Place | null>(null);

  const { results } = await geocode('Ferry Building, San Francisco');
  place.value = results[0];
</script>

<template>
  <VMap :access-token="token">
    <VPlaceAnnotation v-if="place" :place="place" />
  </VMap>
</template>

Prop	Type	Description
`place`	`mapkit.Place`	The place to annotate (required)
`annotation`	`mapkit.AnnotationConstructorOptions`	Optional appearance overrides
`clusteringIdentifier`	`string`	Group with other annotations

VCustomAnnotation

Render arbitrary DOM as the annotation by supplying an element factory. Use it for fully custom markers.

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

  function element() {
    const el = document.createElement('div');
    el.className = 'my-pin';
    el.textContent = '📍';
    return el;
  }
</script>

<template>
  <VMap :access-token="token">
    <VCustomAnnotation :coordinates="[37.3349, -122.009]" :element="element" />
  </VMap>
</template>

Prop	Type	Description
`coordinates`	`[number, number]`	`[latitude, longitude]` (required)
`element`	`() => HTMLElement`	Factory returning the marker DOM (required)
`annotation`	`mapkit.AnnotationConstructorOptions`	Optional appearance overrides
`clusteringIdentifier`	`string`	Group with other annotations

VMapFeatureAnnotation

Renders an annotation for a selectable map feature (a building, point of interest, or territory). Requires selectableMapFeatures on <VMap>.

<VMap
  :access-token="token"
  :selectable-map-features="[mapkit.MapFeatureType.PointOfInterest]"
>
  <VMapFeatureAnnotation :feature="feature" />
</VMap>

Prop	Type	Description
`feature`	`mapkit.MapFeature`	The selected map feature (required)
`annotation`	`mapkit.AnnotationConstructorOptions`	Optional appearance overrides
`clusteringIdentifier`	`string`	Group with other annotations

VAnnotationCallout

Provides custom callout content for its parent annotation using MapKit's AnnotationCalloutDelegate. Nest it inside an annotation component.

<VMap :access-token="token">
  <VMarkerAnnotation :coordinates="[37.3349, -122.009]">
    <VAnnotationCallout>
      <div class="callout">
        <strong>Apple Park</strong>
        <p>One Apple Park Way, Cupertino</p>
      </div>
    </VAnnotationCallout>
  </VMarkerAnnotation>
</VMap>

The default slot becomes the callout's content element when the annotation is selected.

Custom Children with useMapChild

To build your own annotation or overlay, use the useMapChild composable — it injects the map, creates the instance once ready, reacts to prop changes, and removes it on unmount.

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

  const props = defineProps<{ coordinates: [number, number] }>();

  useMapChild<mapkit.MarkerAnnotation>({
    watchSources: () => [props.coordinates],
    create: (mk, map) => {
      const coord = new mk.Coordinate(props.coordinates[0], props.coordinates[1]);
      const a = new mk.MarkerAnnotation(coord);
      map.addAnnotation(a);
      return a;
    },
    remove: (map, a) => map.removeAnnotation(a),
  });
</script>

<template>
  <slot />
</template>

Option	Type	Description
`create`	`(mk, map) => T`	Build the instance and attach it to the map
`remove`	`(map, instance) => void`	Detach the instance
`watchSources`	`() => unknown[]`	Reactive sources that trigger a recreate
`update`	`(mk, map, instance) => void`	Optional in-place update; omit to recreate on change