Skip to content

Components API Reference

Vue3 MapTiler SDK provides a comprehensive set of Vue 3 components for building interactive maps with MapTiler SDK. All components are designed with TypeScript support, reactive data binding, and comprehensive error handling.

MapTiler

The main map component that renders the MapTiler SDK map. This is the core component that provides the map container and manages the MapTiler SDK instance.

Props

PropTypeDefaultDescription
optionsPartial<MapOptions>see belowMap configuration options from MapTiler SDK
register(actions: MapTilerActions) => voidundefinedCallback for registering map actions
debugbooleanfalseEnable debug logging
autoCleanupbooleantrueAutomatically cleanup resources on unmount
containerIdstringrandomContainer id, generated per instance as maptiler-<random>, so two maps on one page never collide
containerClassstring''Custom container class names
onMapError(error: any) => voidundefinedError handling callback. Not onError, which is the error emit's handler key
onMapLoad(map: Map) => voidundefinedLoad success callback. Not onLoad, which is the load emit's handler key

Events

EventPayloadDescription
registerMapTilerActionsFired when map actions are registered
loadMapTilerGLEventFired when the map has finished loading
errorErrorEventFired when an error occurs
clickMapMouseEventFired when the map is clicked
dblclickMapMouseEventFired when the map is double-clicked
contextmenuMapMouseEventFired when right-clicking the map
mousemoveMapMouseEventFired when mouse moves over the map
mouseupMapMouseEventFired when mouse button is released
mousedownMapMouseEventFired when mouse button is pressed
mouseoutMapMouseEventFired when mouse leaves the map
mouseoverMapMouseEventFired when mouse enters the map
movestartMapTilerGLEvent<MouseEvent | TouchEvent | WheelEvent | undefined>Fired when map movement starts
moveMapTilerGLEvent<MouseEvent | TouchEvent | WheelEvent | undefined>Fired during map movement
moveendMapTilerGLEvent<MouseEvent | TouchEvent | WheelEvent | undefined>Fired when map movement ends
zoomstartMapTilerGLEvent<MouseEvent | TouchEvent | WheelEvent | undefined>Fired when zoom starts
zoomMapTilerGLEvent<MouseEvent | TouchEvent | WheelEvent | undefined>Fired during zoom
zoomendMapTilerGLEvent<MouseEvent | TouchEvent | WheelEvent | undefined>Fired when zoom ends
rotatestartMapTilerGLEvent<MouseEvent | TouchEvent | undefined>Fired when rotation starts
rotateMapTilerGLEvent<MouseEvent | TouchEvent | undefined>Fired during rotation
rotateendMapTilerGLEvent<MouseEvent | TouchEvent | undefined>Fired when rotation ends
dragstartMapTilerGLEvent<MouseEvent | TouchEvent | undefined>Fired when dragging starts
dragMapTilerGLEvent<MouseEvent | TouchEvent | undefined>Fired during dragging
dragendMapTilerGLEvent<MouseEvent | TouchEvent | undefined>Fired when dragging ends
pitchstartMapTilerGLEvent<MouseEvent | TouchEvent | undefined>Fired when pitch starts
pitchMapTilerGLEvent<MouseEvent | TouchEvent | undefined>Fired during pitch
pitchendMapTilerGLEvent<MouseEvent | TouchEvent | undefined>Fired when pitch ends
wheelMapWheelEventFired on mouse wheel events
terrainMapTerrainEventFired on terrain events
touchstartMapTouchEventFired when a touch begins
touchmoveMapTouchEventFired as a touch moves
touchendMapTouchEventFired when a touch ends
touchcancelMapTouchEventFired when a touch is interrupted
boxzoomstartMapTilerZoomEventFired when a box zoom begins
boxzoomendMapTilerZoomEventFired when a box zoom completes
boxzoomcancelMapTilerZoomEventFired when a box zoom is cancelled
idleMapTilerGLEventFired when the map stops rendering
renderMapTilerGLEventFired on every frame the map draws
resizeMapTilerGLEventFired when the map container resizes
removeMapTilerGLEventFired when the map is destroyed
dataMapDataEventFired when any map data loads or changes
dataloadingMapDataEventFired when data begins loading
dataabortMapDataEventFired when a data request is aborted
tiledataloadingMapDataEventFired when a tile begins loading
sourcedataMapSourceDataEventFired when source data loads or changes
sourcedataloadingMapSourceDataEventFired when source data begins loading
sourcedataabortMapSourceDataEventFired when a source request is aborted
styledataMapStyleDataEventFired when the style loads or changes
styleimagemissingMapStyleImageMissingEventFired when the style needs an image it does not have
webglcontextlostMapContextEventFired when the WebGL context is lost
webglcontextrestoredMapContextEventFired when the WebGL context is restored

Slots

SlotDescription
defaultMain content slot for child components
loadingContent shown while map is loading
errorContent shown when map encounters an error

Example

vue
<template>
  <MapTiler
    :options="mapOptions"
    :debug="true"
    @load="onMapLoad"
    @error="onMapError"
    style="height: 500px"
  >
    <template #loading>
      <div class="loading">Loading map...</div>
    </template>

    <template #error>
      <div class="error">Failed to load map</div>
    </template>

    <!-- Child components -->
    <GeoJsonSource :data="geoJsonData">
      <FillLayer :style="fillStyle" />
    </GeoJsonSource>
  </MapTiler>
</template>

<script setup>
import { ref } from 'vue';
import { MapTiler, GeoJsonSource, FillLayer } from 'vue3-maptiler-gl';

const mapOptions = ref({
  style: 'https://demotiles.maplibre.org/style.json',
  center: [0, 0],
  zoom: 2,
});

const geoJsonData = ref({
  type: 'FeatureCollection',
  features: [],
});

const fillStyle = ref({
  'fill-color': '#088',
  'fill-opacity': 0.8,
});

function onMapLoad(map) {
  console.log('Map loaded:', map);
}

function onMapError(error) {
  console.error('Map error:', error);
}
</script>

GeoJsonSource

A component for adding GeoJSON data sources to the map. This component provides the data that can be styled by layer components. It supports reactive data updates, clustering, and comprehensive error handling.

Props

PropTypeDefaultDescription
idstringundefinedUnique identifier for the source
dataGeoJSONSourceSpecification['data']{ type: 'FeatureCollection', features: [] }GeoJSON data or URL to GeoJSON
optionsPartial<GeoJSONSourceSpecification>{}Additional GeoJSON source options
debugbooleanfalseEnable debug logging
autoCleanupbooleantrueAutomatically cleanup resources on unmount
register(actions: CreateGeoJsonSourceActions) => voidundefinedCallback for registering source actions
onSourceLoad(source: GeoJSONSource) => voidundefinedLoad success callback. Not onLoad, which is the load emit's handler key
onSourceError(error: any) => voidundefinedError handling callback. Not onError, which is the error emit's handler key
debounceDelaynumber100Delay in ms before a data change is pushed to the source
onDataUpdate(data: GeoJSONSourceSpecification['data']) => voidundefinedData update callback

Events

EventPayloadDescription
registerCreateGeoJsonSourceActionsFired when source is registered
loadGeoJSONSourceFired when source is loaded
errorErrorFired when an error occurs
data-updateGeoJSONSourceSpecification['data']Fired when data is updated

Example

vue
<template>
  <MapTiler :options="mapOptions">
    <GeoJsonSource id="my-source" :data="geoJsonData" :options="clusterOptions">
      <CircleLayer :style="circleStyle" />
    </GeoJsonSource>
  </MapTiler>
</template>

<script setup>
import { ref } from 'vue';
import { MapTiler, GeoJsonSource, CircleLayer } from 'vue3-maptiler-gl';

const mapOptions = ref({
  style: 'https://demotiles.maplibre.org/style.json',
  center: [0, 0],
  zoom: 2,
});

// Clustering is source configuration, so it goes in `options` rather than in
// props of its own.
const clusterOptions = ref({
  cluster: true,
  clusterMaxZoom: 14,
  clusterRadius: 50,
});

const geoJsonData = ref({
  type: 'FeatureCollection',
  features: [
    {
      type: 'Feature',
      geometry: {
        type: 'Point',
        coordinates: [0, 0],
      },
      properties: {
        name: 'Sample Point',
      },
    },
  ],
});

const circleStyle = ref({
  'circle-radius': 6,
  'circle-color': '#007cbf',
});
</script>

FillLayer

A component for rendering filled polygons from a data source. Supports all MapTiler SDK fill layer properties with reactive updates and comprehensive event handling.

Props

PropTypeDefaultDescription
idstringundefinedUnique identifier for the layer
sourcestring | objectundefinedData source for the layer
sourceLayerstringundefinedSource layer name for vector sources
filterFilterSpecificationundefinedFilter expression to apply to the layer; the layer is created with ['all'] when omitted
styleFillLayerStyleundefinedStyle configuration for the fill layer; an omitted style contributes nothing
maxzoomnumberundefinedMaximum zoom level for layer visibility; the layer is created with 24 when omitted
minzoomnumberundefinedMinimum zoom level for layer visibility; the layer is created with 0 when omitted
metadataobjectundefinedArbitrary metadata for the layer
beforeIdstringundefinedID of layer before which to insert this layer
visiblebooleantrueWhether the layer is visible
register(actions: CreateLayerActions<FillLayerSpecification>, map: Map) => voidundefinedCallback receiving the layer's actions once it exists

Events

EventPayloadDescription
registerCreateLayerActions<FillLayerSpecification>Fired when layer is registered
clickMapLayerMouseEventFired when layer is clicked
dblclickMapLayerMouseEventFired when layer is double-clicked
mousedownMapLayerMouseEventFired when mouse button is pressed on layer
mouseupMapLayerMouseEventFired when mouse button is released on layer
mousemoveMapLayerMouseEventFired when mouse moves over layer
mouseenterMapLayerMouseEventFired when mouse enters layer
mouseleaveMapLayerMouseEventFired when mouse leaves layer
mouseoverMapLayerMouseEventFired when mouse is over layer
mouseoutMapLayerMouseEventFired when mouse leaves layer
contextmenuMapLayerMouseEventFired when right-clicking layer
touchstartMapLayerTouchEventFired when touch starts on layer
touchendMapLayerTouchEventFired when touch ends on layer
touchcancelMapLayerTouchEventFired when touch is cancelled on layer

Example

vue
<template>
  <MapTiler :options="mapOptions">
    <GeoJsonSource :data="polygonData">
      <FillLayer
        id="polygon-fill"
        :style="fillStyle"
        :filter="['==', 'type', 'polygon']"
        @click="onPolygonClick"
      />
    </GeoJsonSource>
  </MapTiler>
</template>

<script setup>
import { ref } from 'vue';
import { MapTiler, GeoJsonSource, FillLayer } from 'vue3-maptiler-gl';

const mapOptions = ref({
  style: 'https://demotiles.maplibre.org/style.json',
  center: [0, 0],
  zoom: 2,
});

const polygonData = ref({
  type: 'FeatureCollection',
  features: [],
});

const fillStyle = ref({
  'fill-color': [
    'case',
    ['boolean', ['feature-state', 'hover'], false],
    '#627BC1',
    '#41B883',
  ],
  'fill-opacity': 0.8,
});

function onPolygonClick(event) {
  console.log('Polygon clicked:', event.features[0]);
}
</script>

CircleLayer

A component for rendering circles from point data sources. Perfect for displaying point data with customizable radius, color, and stroke properties.

Props

PropTypeDefaultDescription
idstringundefinedUnique identifier for the layer
sourcestring | objectundefinedData source for the layer
sourceLayerstringundefinedSource layer name for vector sources
filterFilterSpecification['all']Filter expression to apply to the layer
styleCircleLayerStyle{}Style configuration for the circle layer
maxzoomnumberundefinedMaximum zoom level for layer visibility; the layer is created with 24 when omitted
minzoomnumberundefinedMinimum zoom level for layer visibility; the layer is created with 0 when omitted
metadataobjectundefinedArbitrary metadata for the layer
beforeIdstringundefinedID of layer before which to insert this layer
visiblebooleantrueWhether the layer is visible
register(actions: CreateLayerActions<CircleLayerSpecification>, map: Map) => voidundefinedCallback receiving the layer's actions once it exists
debugbooleanfalseEnable debug logging

Events

Same events as FillLayer (click, mousemove, etc.)

Example

vue
<template>
  <MapTiler :options="mapOptions">
    <GeoJsonSource :data="pointData">
      <CircleLayer id="points" :style="circleStyle" @click="onPointClick" />
    </GeoJsonSource>
  </MapTiler>
</template>

<script setup>
import { ref } from 'vue';
import { MapTiler, GeoJsonSource, CircleLayer } from 'vue3-maptiler-gl';

const mapOptions = ref({
  style: 'https://demotiles.maplibre.org/style.json',
  center: [0, 0],
  zoom: 2,
});

const pointData = ref({
  type: 'FeatureCollection',
  features: [],
});

const circleStyle = ref({
  'circle-radius': ['interpolate', ['linear'], ['zoom'], 5, 2, 15, 10],
  'circle-color': [
    'interpolate',
    ['linear'],
    ['get', 'magnitude'],
    1,
    '#ffffcc',
    5,
    '#fd8d3c',
    10,
    '#800026',
  ],
  'circle-stroke-width': 1,
  'circle-stroke-color': '#fff',
});

function onPointClick(event) {
  console.log('Point clicked:', event.features[0]);
}
</script>

LineLayer

A component for rendering lines from line data sources. Ideal for displaying routes, boundaries, and other linear features with customizable styling.

Props

PropTypeDefaultDescription
idstringundefinedUnique identifier for the layer
sourcestring | objectundefinedData source for the layer
sourceLayerstringundefinedSource layer name for vector sources
filterFilterSpecificationundefinedFilter expression to apply to the layer; the layer is created with ['all'] when omitted
styleLineLayerStyleundefinedStyle configuration for the line layer; an omitted style contributes nothing
maxzoomnumberundefinedMaximum zoom level for layer visibility; the layer is created with 24 when omitted
minzoomnumberundefinedMinimum zoom level for layer visibility; the layer is created with 0 when omitted
metadataobjectundefinedArbitrary metadata for the layer
beforeIdstringundefinedID of layer before which to insert this layer
visiblebooleantrueWhether the layer is visible
register(actions: CreateLayerActions<LineLayerSpecification>, map: Map) => voidundefinedCallback receiving the layer's actions once it exists

Events

Same events as FillLayer (click, mousemove, etc.)

Example

vue
<template>
  <MapTiler :options="mapOptions">
    <GeoJsonSource :data="lineData">
      <LineLayer id="routes" :style="lineStyle" @click="onLineClick" />
    </GeoJsonSource>
  </MapTiler>
</template>

<script setup>
import { ref } from 'vue';
import { MapTiler, GeoJsonSource, LineLayer } from 'vue3-maptiler-gl';

const mapOptions = ref({
  style: 'https://demotiles.maplibre.org/style.json',
  center: [0, 0],
  zoom: 2,
});

const lineData = ref({
  type: 'FeatureCollection',
  features: [],
});

const lineStyle = ref({
  'line-color': '#007cbf',
  'line-width': ['interpolate', ['linear'], ['zoom'], 5, 1, 15, 8],
  'line-opacity': 0.8,
});

function onLineClick(event) {
  console.log('Line clicked:', event.features[0]);
}
</script>

SymbolLayer

A component for rendering symbols (icons and text) from point data sources. Perfect for displaying labels, icons, and other symbolic representations on the map.

Props

PropTypeDefaultDescription
idstringundefinedUnique identifier for the layer
sourcestring | objectundefinedData source for the layer
sourceLayerstringundefinedSource layer name for vector sources
filterFilterSpecificationundefinedFilter expression to apply to the layer; the layer is created with ['all'] when omitted
styleSymbolLayerStyleundefinedStyle configuration for the symbol layer; an omitted style contributes nothing
maxzoomnumberundefinedMaximum zoom level for layer visibility; the layer is created with 24 when omitted
minzoomnumberundefinedMinimum zoom level for layer visibility; the layer is created with 0 when omitted
metadataobjectundefinedArbitrary metadata for the layer
beforeIdstringundefinedID of layer before which to insert this layer
visiblebooleantrueWhether the layer is visible
register(actions: CreateLayerActions<SymbolLayerSpecification>, map: Map) => voidundefinedCallback receiving the layer's actions once it exists

Events

Same events as FillLayer (click, mousemove, etc.)

Example

vue
<template>
  <MapTiler :options="mapOptions">
    <GeoJsonSource :data="pointData">
      <SymbolLayer id="labels" :style="symbolStyle" @click="onSymbolClick" />
    </GeoJsonSource>
  </MapTiler>
</template>

<script setup>
import { ref } from 'vue';
import { MapTiler, GeoJsonSource, SymbolLayer } from 'vue3-maptiler-gl';

const mapOptions = ref({
  style: 'https://demotiles.maplibre.org/style.json',
  center: [0, 0],
  zoom: 2,
});

const pointData = ref({
  type: 'FeatureCollection',
  features: [],
});

const symbolStyle = ref({
  'text-field': ['get', 'name'],
  'text-font': ['Open Sans Regular'],
  'text-size': 12,
  'text-color': '#333',
  'text-halo-color': '#fff',
  'text-halo-width': 1,
  'text-anchor': 'top',
  'text-offset': [0, 1],
});

function onSymbolClick(event) {
  console.log('Symbol clicked:', event.features[0]);
}
</script>

Marker

A component for adding HTML markers to the map. Supports custom HTML content, dragging, and comprehensive styling options.

Props

PropTypeDefaultDescription
lnglatLngLatLikeundefinedGeographic coordinates for the marker
popupPopupundefinedPopup to associate with the marker
optionsMarkerOptions{}Marker configuration options
draggablebooleanundefinedWhether the marker is draggable; omitted leaves the option unset, and MapTiler does not drag
elementHTMLElementundefinedCustom HTML element for the marker
offsetPointLikeundefinedOffset from the marker's position
anchorAnchorundefinedAnchor point for the marker
colorstringundefinedColor of the default marker
clickTolerancenumberundefinedTolerance for click events
rotationnumberundefinedRotation angle in degrees
rotationAlignmentAlignmentundefinedRotation alignment relative to the map
pitchAlignmentAlignmentundefinedPitch alignment relative to the map
scalenumberundefinedScale factor for the marker
occludedOpacitynumberundefinedOpacity when marker is occluded

Events

EventPayloadDescription
dragstartEventFired when dragging starts
dragEventFired during dragging
dragendEventFired when dragging ends

Example

vue
<template>
  <MapTiler :options="mapOptions">
    <Marker
      :lnglat="markerPosition"
      :draggable="true"
      @dragend="onMarkerDragEnd"
    >
      <div class="custom-marker">📍</div>
    </Marker>
  </MapTiler>
</template>

<script setup>
import { ref } from 'vue';
import { MapTiler, Marker } from 'vue3-maptiler-gl';

const mapOptions = ref({
  style: 'https://demotiles.maplibre.org/style.json',
  center: [0, 0],
  zoom: 2,
});

const markerPosition = ref([0, 0]);

function onMarkerDragEnd(event) {
  markerPosition.value = event.target.getLngLat().toArray();
  console.log('Marker moved to:', markerPosition.value);
}
</script>

<style>
.custom-marker {
  font-size: 24px;
  cursor: pointer;
}
</style>

A component for displaying popup windows on the map. Supports custom HTML content, positioning, and comprehensive event handling.

Props

PropTypeDefaultDescription
classNamestringundefinedCSS class name for the popup
lnglatLngLatLikeundefinedGeographic coordinates for the popup
showbooleantrueWhether the popup is visible
withMapbooleantrueWhether to attach popup to the map
optionsPopupOptionsundefinedPopup configuration options; an omitted object contributes nothing
htmlstringundefinedHTML content for the popup
maxWidthstringundefinedMaximum width of the popup
closeButtonbooleantrueWhether to show close button
closeOnClickbooleantrueWhether to close on map click
closeOnEscapebooleantrueWhether to close on escape key

Events

EventPayloadDescription
closevoidFired when popup is closed
openvoidFired when popup is opened
update:showbooleanFired when show state changes (for v-model support)

Example

vue
<template>
  <MapTiler :options="mapOptions">
    <Popup :lnglat="popupPosition" :close-button="true" @close="onPopupClose">
      <div class="popup-content">
        <h3>Hello World!</h3>
        <p>This is a popup at {{ popupPosition }}.</p>
      </div>
    </Popup>
  </MapTiler>
</template>

<script setup>
import { ref } from 'vue';
import { MapTiler, Popup } from 'vue3-maptiler-gl';

const mapOptions = ref({
  style: 'https://demotiles.maplibre.org/style.json',
  center: [0, 0],
  zoom: 2,
});

const popupPosition = ref([0, 0]);

function onPopupClose() {
  console.log('Popup closed');
}
</script>

<style>
.popup-content {
  padding: 10px;
  max-width: 200px;
}
</style>

Image

A component for managing and loading images for use in MapTiler SDK styles. Supports multiple image formats and provides loading state management.

Props

PropTypeDefaultDescription
imagesImageItem[][]Array of images to load
optionsPartial<StyleImageMetadata>undefinedDefault options applied to all images; an omitted object contributes nothing
showLoadingbooleantrueWhether to show loading state
forceRecreateOnDimensionChangebooleantrueRemove and re-add an image whose dimensions changed, avoiding MapTiler's "width and height must be the same as the previous version" error
debugbooleanundefinedWhether to enable debug logging

Events

EventPayloadDescription
erroranyFired when an image fails to load

ImageItem Interface

PropertyTypeDescription
idstringUnique identifier for the image
imageImageDatas | stringImage data (URL string or ImageData/HTMLImageElement)
optionsPartial<StyleImageMetadata>Optional image metadata and options

Example

vue
<template>
  <MapTiler :options="mapOptions">
    <Image :images="mapImages" :show-loading="true" />
    <GeoJsonSource :data="pointData">
      <SymbolLayer :style="symbolStyle" />
    </GeoJsonSource>
  </MapTiler>
</template>

<script setup>
import { ref } from 'vue';
import { MapTiler, Image, GeoJsonSource, SymbolLayer } from 'vue3-maptiler-gl';

const mapOptions = ref({
  style: 'https://demotiles.maplibre.org/style.json',
  center: [0, 0],
  zoom: 2,
});

const pointData = ref({
  type: 'FeatureCollection',
  features: [],
});

const mapImages = ref([
  {
    id: 'custom-marker',
    image: '/path/to/marker.png',
    options: { sdf: false },
  },
]);

const symbolStyle = ref({
  'icon-image': 'custom-marker',
  'icon-size': 1.5,
});
</script>

GeolocateControls

A component for adding geolocation controls to the map. Provides user location tracking with comprehensive event handling and error management.

Props

PropTypeDefaultDescription
positionControlPosition'bottom-right'Position of the control on the map
optionsGeolocateControlOptions{}Geolocate control configuration options
debugbooleanfalseEnable debug logging
autoCleanupbooleantrueAutomatically cleanup resources on unmount
onGeolocateError(error: any) => voidundefinedError handling callback. Not onError, which is the error emit's handler key
onGeolocateSuccess(data: GeolocateSuccess) => voidundefinedSuccess callback. Not onGeolocate, which is the geolocate emit's handler key
onTrackingStart(data: GeolocateSuccess) => voidundefinedCallback when user location tracking starts
onTrackingEnd(data: GeolocateSuccess) => voidundefinedCallback when user location tracking ends
onOutOfMaxBounds(data: GeolocateSuccess) => voidundefinedCallback when user location is out of max bounds

Events

EventPayloadDescription
registerGeolocateControlFired when control is registered
geolocateGeolocateSuccessFired when geolocation is successful
errorGeolocationPositionErrorFired when geolocation error occurs
trackuserlocationstartGeolocateSuccessFired when location tracking starts
trackuserlocationendGeolocateSuccessFired when location tracking ends
outofmaxboundsGeolocateSuccessFired when location is out of max bounds

The event names are MapTiler's own, so @trackuserlocationstart — not @trackingstart. The onTrackingStart / onTrackingEnd props above keep the shorter names.

Example

vue
<template>
  <MapTiler :options="mapOptions">
    <GeolocateControls
      position="top-right"
      :options="geolocateOptions"
      @geolocate="onGeolocate"
      @error="onGeolocateError"
    />
  </MapTiler>
</template>

<script setup>
import { ref } from 'vue';
import { MapTiler, GeolocateControls } from 'vue3-maptiler-gl';

const mapOptions = ref({
  style: 'https://demotiles.maplibre.org/style.json',
  center: [0, 0],
  zoom: 2,
});

const geolocateOptions = ref({
  positionOptions: {
    enableHighAccuracy: true,
  },
  trackUserLocation: true,
});

function onGeolocate(data) {
  console.log('User location:', data.coords);
}

function onGeolocateError(error) {
  console.error('Geolocation error:', error);
}
</script>