---
url: /reference/items/MapboxMap/js-api.md
---
# JS API
This page documents thirteen components — a single root component, `MapboxMap`, which owns the Mapbox `Map` instance, plus the twelve children below — built on the `AbstractMapboxMapChild` (and, for controls, `AbstractMapboxControl`) base classes. The [`StoreLocator`](/reference/items/StoreLocator/) orchestrator completes the family on its own page. Every child resolves the closest parent `MapboxMap` on its own and registers itself against its map once it is loaded.
[Register](/guide/usage/#registering-components) each component you use — ideally behind a lazy [`importWhen*` helper](https://js-toolkit.studiometa.dev/api/helpers/importWhenVisible.html) so the heavy `mapbox-gl` dependency stays out of your main bundle (see [Lazy loading](/reference/items/MapboxMap/#lazy-loading)).
* **[Map](#map)** — `MapboxMap`
* **[Markers & Popups](#markers-popups)** — `MapboxMarker`, `MapboxPopup`
* **[Controls](#controls)** — `MapboxNavigationControl`, `MapboxGeolocateControl`, `MapboxFullscreenControl`, `MapboxGeocoder`
* **[Data](#data)** — `MapboxSource`, `MapboxLayer`, `MapboxImage`, `MapboxImages`
* **[Cluster](#cluster)** — `MapboxCluster`, `MapboxClusterItem` (see also the [`StoreLocator`](/reference/items/StoreLocator/) orchestrator)
* **[AbstractMapboxMapChild](#abstractmapboxmapchild)** — the shared base class
## Providing the `mapbox-gl` dependency
By default the components resolve `mapbox-gl` (and the optional `@mapbox/mapbox-gl-geocoder`) with a lazy `import()` the first time a map is built, so nothing needs configuring — keep `mapbox-gl` installed and it just works, staying out of your main bundle until a map is on the page.
To control which `mapbox-gl` the components use — a pinned version, a self-hosted build (for example a same-origin worker under a strict CSP), or a module served from an import map or a CDN — inject your own instance once, before the components mount:
```js
import mapboxgl from 'mapbox-gl';
import MapboxGeocoder from '@mapbox/mapbox-gl-geocoder';
import { provideMapboxGl, provideMapboxGeocoder } from '@studiometa/ui-mapbox';
provideMapboxGl(mapboxgl);
provideMapboxGeocoder(MapboxGeocoder); // optional geocoder peer
```
Once provided, `@studiometa/ui-mapbox` never imports `mapbox-gl` by specifier — it uses the instance you handed it. `resolveMapboxGl()` and `resolveMapboxGeocoder()` are exported too if you want to trigger and await resolution yourself (for example to preload the module).
## Reactivity and updates
To move the map, change its data or update a marker after mount, reach for the underlying Mapbox objects directly through the component instances:
```js
import { getInstance } from '@studiometa/js-toolkit';
// The Mapbox `Map` instance is exposed on the `MapboxMap` component.
const mapboxMap = getInstance(element, MapboxMap);
mapboxMap.map.setCenter([2.35, 48.86]);
mapboxMap.map.setZoom(12);
// Markers, popups and sources expose their own Mapbox object too.
marker.marker.setLngLat([2.29, 48.86]);
```
Every component documents the Mapbox object it exposes (`map`, `marker`, `popup`, `control`, …) in its **Getters** section below.
::: tip Switching base style keeps your layers
Calling `map.setStyle(…)` wipes the entire style — every source, layer and sprite — while the map instance and the still-mounted child components survive. Each map child subscribes to the map's `style.load` and **re-injects** its contribution automatically, so your declarative sources, layers, images and clusters re-appear on the new base style instead of silently vanishing. You can switch the base style at runtime without re-declaring your data.
:::
## Map
### MapboxMap
Display an interactive Mapbox GL map. This is the root component of the system and the parent of every other component. It instantiates the Mapbox `Map` lazily and re-emits its events.
#### Options
##### `access-token`
* Type: `String`
Mapbox GL [access token](https://docs.mapbox.com/help/getting-started/access-tokens/) (required).
##### `zoom`
* Type: `Number`
Initial zoom level.
##### `center`
* Type: `Array`
* Default: `[0, 0]`
Initial center as `[longitude, latitude]`.
##### `map-options`
* Type: `Object`
* Default: `{}`
Any other [Mapbox `Map` option](https://docs.mapbox.com/mapbox-gl-js/api/map/#map-parameters), spread into the constructor. This is where `style`, `pitch`, `bearing`, `bounds`, … go.
The `access-token`, `zoom` and `center` options act as overridable defaults, then `map-options` is spread into the [Mapbox `Map` constructor](https://docs.mapbox.com/mapbox-gl-js/api/map/#map-parameters). The `container` is always resolved from the component (the `container` ref, falling back to the root element) and can not be overridden. Use `map-options` for anything the convenience options above do not cover — most notably the map [`style`](https://docs.mapbox.com/mapbox-gl-js/api/map/#map-parameters):
```html
```
#### Refs
##### `container`
* Type: `HTMLElement`
The element used as the map container. Falls back to the root element when omitted.
#### Getters
##### `map`
* Type: `mapboxgl.Map`
The underlying Mapbox GL map instance.
##### `isLoaded`
* Type: `boolean`
Whether the map has finished loading.
#### Events
The component emits a custom `map-load` event, plus all the common Mapbox GL map events prefixed with `map-` to avoid conflicts with native events. Each handler receives the corresponding Mapbox event object (the `map-load` handler receives the `map` instance).
##### `map-load`
The map finished loading (custom event).
##### `map-idle`
The map is idle after rendering.
##### `map-render`
A frame is rendered.
##### `map-resize`
The map container is resized.
##### `map-remove`
The map is removed.
##### `map-error`
An error occurred.
##### `map-click`
A click on the map.
##### `map-dblclick`
A double-click on the map.
##### `map-mouseenter`
The pointer enters the map canvas.
##### `map-mouseleave`
The pointer leaves the map canvas.
##### `map-mousemove`
The pointer moves over the map.
##### `map-movestart`
Map movement starts (pan, zoom, rotate).
##### `map-move`
The map is moving.
##### `map-moveend`
Map movement ends.
##### `map-zoomstart`
A zoom transition starts.
##### `map-zoom`
The zoom level changes.
##### `map-zoomend`
A zoom transition ends.
##### `map-rotatestart`
Rotation starts.
##### `map-rotate`
The map is rotating.
##### `map-rotateend`
Rotation ends.
##### `map-pitchstart`
A pitch transition starts.
##### `map-pitch`
The pitch changes.
##### `map-pitchend`
A pitch transition ends.
##### `map-dragstart`
A drag starts.
##### `map-drag`
The map is being dragged.
##### `map-dragend`
A drag ends.
Listen to these events from a parent component with `on` methods:
```js
import { Base, createApp } from '@studiometa/js-toolkit';
import { MapboxMap } from '@studiometa/ui-mapbox';
class App extends Base {
static config = {
name: 'App',
components: { MapboxMap },
};
onMapboxMapMapLoad({ args: [map] }) {
console.log('Map is ready', map);
}
onMapboxMapMapClick({ args: [event] }) {
console.log('Clicked at', event.lngLat);
}
onMapboxMapMapZoomend({ args: [event] }) {
console.log('New zoom level', event.target.getZoom());
}
}
createApp(App);
```
## Markers & Popups
### MapboxMarker
Add a [marker](https://docs.mapbox.com/mapbox-gl-js/api/markers/#marker) to the map. A `MapboxPopup` nested inside the marker is automatically attached to it.
#### Options
##### `lng-lat`
* Type: `Array`
* Default: `[0, 0]`
Marker position as `[longitude, latitude]`.
##### `marker-options`
* Type: `Object`
* Default: `{}`
[Mapbox Marker options](https://docs.mapbox.com/mapbox-gl-js/api/markers/#marker) (color, anchor, draggable, …).
#### Getters
##### `marker`
* Type: `mapboxgl.Marker`
The underlying Marker instance.
##### `popup`
* Type: `MapboxPopup`
The first nested `MapboxPopup` child, if any.
### MapboxPopup
Display a [popup](https://docs.mapbox.com/mapbox-gl-js/api/markers/#popup) on the map. It can be used standalone (placed directly on the map at a given position) or nested inside a `MapboxMarker` (attached to the marker, no `lng-lat` needed). The popup content is taken from the element's inner HTML.
#### Options
##### `lng-lat`
* Type: `Array`
* Default: `[0, 0]`
Popup position as `[longitude, latitude]` (standalone popups only).
##### `popup-options`
* Type: `Object`
* Default: `{}`
[Mapbox Popup options](https://docs.mapbox.com/mapbox-gl-js/api/markers/#popup).
#### Getters
##### `popup`
* Type: `mapboxgl.Popup`
The underlying Popup instance.
## Controls
All controls extend [`AbstractMapboxMapChild`](#abstractmapboxmapchild) and expose the underlying Mapbox control through a `control` getter. They share a `position` option and are added to the map on mount, removed on destroy.
### MapboxNavigationControl
Add zoom in/out and compass controls to the map.
#### Options
##### `position`
* Type: `String`
* Default: `'top-right'`
Control position: `top-left`, `top-right`, `bottom-left` or `bottom-right`.
##### `show-compass`
* Type: `Boolean`
* Default: `false`
Show the compass button.
##### `show-zoom`
* Type: `Boolean`
* Default: `false`
Show the zoom in/out buttons.
##### `visualize-pitch`
* Type: `Boolean`
* Default: `false`
Visualize the pitch on the compass button.
### MapboxGeolocateControl
Add a button that uses the browser's geolocation API to locate the user on the map.
#### Options
##### `position`
* Type: `String`
* Default: `'top-right'`
Control position.
##### `position-options`
* Type: `Object`
Browser [`PositionOptions`](https://developer.mozilla.org/en-US/docs/Web/API/PositionOptions).
##### `fit-bounds-options`
* Type: `Object`
[`FitBoundsOptions`](https://docs.mapbox.com/mapbox-gl-js/api/map/#map#fitbounds) used when tracking.
##### `track-user-location`
* Type: `Boolean`
* Default: `false`
Continuously track the user location.
##### `show-accuracy-circle`
* Type: `Boolean`
* Default: `false`
Show the accuracy circle around the user location.
##### `show-user-location`
* Type: `Boolean`
* Default: `false`
Show the user location dot.
##### `show-user-heading`
* Type: `Boolean`
* Default: `false`
Show the user heading indicator.
### MapboxFullscreenControl
Add a button that toggles the map fullscreen.
#### Options
##### `position`
* Type: `String`
* Default: `'top-right'`
Control position.
### MapboxGeocoder
Add an address search control powered by [`@mapbox/mapbox-gl-geocoder`](https://github.com/mapbox/mapbox-gl-geocoder). Install the optional `@mapbox/mapbox-gl-geocoder` peer dependency to use it.
::: tip Optional, loaded on demand
`@mapbox/mapbox-gl-geocoder` is an optional peer dependency. It is loaded lazily with a dynamic `import()` when a `MapboxGeocoder` mounts, so the rest of the package works without it installed. If you use this component, add it to your project: `npm install @mapbox/mapbox-gl-geocoder`.
:::
#### Options
##### `add-to-map`
* Type: `Boolean`
* Default: `false`
Add the geocoder to the map as a control. Otherwise it is rendered inside the component's element.
##### `options`
* Type: `Object`
* Default: `{}`
[Geocoder options](https://github.com/mapbox/mapbox-gl-geocoder/blob/master/API.md#parameters). Non-serializable options (`filter`, `externalGeocoder`, `render`, `getItemValue`, `localGeocoder`) are not supported.
The `accessToken` is inherited from the parent `MapboxMap` when it is not set in `options`.
#### Getters
##### `control`
* Type: `MapboxGeocoder`
The underlying `mapbox-gl-geocoder` control instance.
##### `target`
* Type: `Map | HTMLElement`
Where the control is mounted, depending on `add-to-map`.
#### Events
##### `map-result`
* Payload: `result`
Emitted when the geocoder resolves an address, carrying the geocoder's `result` (its selected feature).
## Data
### MapboxSource
Add a [source](https://docs.mapbox.com/style-spec/reference/sources/) to the map. On destroy, every layer tied to the source is removed before the source itself.
#### Options
##### `id`
* Type: `String`
Unique source id, referenced by layers.
##### `source`
* Type: `Object`
A [source specification](https://docs.mapbox.com/style-spec/reference/sources/), e.g. `{ "type": "geojson", "data": … }`.
#### Refs
##### `geojson`
* Type: `HTMLScriptElement`
Optional `