--- url: /reference/items/MapboxMap/examples.md --- # Examples Every component in the family is self-registering, so each example registers exactly the components it uses — `MapboxMap` on its own for a bare map, plus the child components it declares (markers, popups, controls, sources, layers, images, clusters). Each child resolves its parent `MapboxMap` on its own once mounted. Each example loads the [Mapbox GL stylesheet](./#installation) from a CDN and picks a Mapbox style through the `map-options` option, which forwards any [`Map` option](https://docs.mapbox.com/mapbox-gl-js/api/map/#map-parameters) to mapbox-gl. Replace the access token with your own [access token](https://docs.mapbox.com/help/getting-started/access-tokens/); the token used here is a public, restricted demo token. Child components that should not take part in the normal document flow (markers, popups, controls, sources, layers, images, clusters) are wrapped in a `hidden` element: their markup is only used as a declarative definition, the actual rendering happens on the map canvas. ## Basic map A minimal interactive map with a `container` ref and a size set through CSS. ## Markers and popups Add a `MapboxMarker` for each point. A `MapboxPopup` nested inside a marker is attached to it and opens on click; a `MapboxPopup` placed directly on the map (with its own `lng-lat`) is displayed as a standalone popup. The popup content is taken from the element's inner HTML. ## Navigation, geolocate and fullscreen controls Controls are added by declaring the matching child component. Each control accepts a `position` option (`top-left`, `top-right`, `bottom-left`, `bottom-right`). This example also demonstrates the `map-options` option beyond the style: it sets a `pitch` and `bearing` for a tilted, rotated camera — click the navigation control's compass to reset the bearing. ## Geocoder The `MapboxGeocoder` component adds an address search field powered by [`@mapbox/mapbox-gl-geocoder`](https://github.com/mapbox/mapbox-gl-geocoder). The `add-to-map` option controls where the input is rendered. The search itself calls the Mapbox Geocoding API, so it needs an access token authorized for geocoding; the examples below are shown as static markup. With `add-to-map`, the geocoder is added to the map as a Mapbox control, overlaid on the map canvas: ```html
``` Without `add-to-map`, the geocoder is rendered inside the component's own element, so you can place the search field anywhere in your layout, outside the map canvas: ```html
``` The access token is inherited from the parent `MapboxMap` when it is not set in the geocoder `options`. ## Source and layer Add a [source](https://docs.mapbox.com/style-spec/reference/sources/) with `MapboxSource`, then render it with one or more `MapboxLayer` elements referencing the source `id`. The `layer` option accepts a full [layer specification](https://docs.mapbox.com/style-spec/reference/layers/). ## Images Register images against the map sprite so they can be referenced from a symbol layer's `icon-image`. Use `MapboxImage` for a single image, or `MapboxImages` to load several at once through its `sources` option. Both emit a `map-ready` event once the image(s) are loaded. The symbol layer below pairs each `icon-image` with a `text-field` label. ## Cluster The `MapboxCluster` component is a clustered GeoJSON **source driver**: it derives its source from the `MapboxClusterItem`s in its subtree, wiring the cluster circles, the cluster count labels and the unclustered points, together with the click-to-zoom interaction. Each item is at once a list entry and a map feature — the same markup drives both. The example below declares a hidden list of items; click a cluster to zoom in and split it. ### Items drive the source {#cluster-items} The cluster owns no authored data. Each point is a `MapboxClusterItem` that self-registers with the closest `MapboxCluster` ancestor; the cluster derives a clustered GeoJSON `FeatureCollection` from the registry and rebuilds it (debounced) whenever items mount or unmount: ```html ``` The cluster reports a click on an unclustered point through its `map-item-click` event but never selects or flies on its own. To turn this into a full "find a store near you" experience — selection, popups, viewport filtering and address search — wrap the cluster in a [`StoreLocator`](/reference/items/StoreLocator/) orchestrator. ## Listening to map events The `MapboxMap` component re-emits the Mapbox map events with a `map-` prefix to avoid conflicts with native events. Listen to them from a parent component by defining `on` methods — for example `onMapboxMapMapClick` or `onMapboxMapMapLoad`. ```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 loaded', map); } onMapboxMapMapClick({ args: [event] }) { console.log('Clicked at', event.lngLat); } } createApp(App); ```