@studiometa/ui-mapbox 2.0.0-alpha.0 → 2.0.0-alpha.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,481 @@
1
+ # Examples
2
+
3
+ Every component in the family is registered independently, 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](index.md#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.
4
+
5
+ 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.
6
+
7
+ ## Basic map
8
+
9
+ A minimal interactive map with a `container` ref and a size set through CSS.
10
+
11
+ ```twig
12
+ <link rel="stylesheet" href="https://esm.sh/mapbox-gl@3.13.0/dist/mapbox-gl.css" />
13
+
14
+ <div
15
+ data-component="MapboxMap"
16
+ data-option-access-token="pk.eyJ1IjoiYWdlbmNlc3R1ZGlvbWV0YSIsImEiOiJjbXM5NTBycHMwa2Z4MndxeW02YndscmQyIn0.UitMikKpq-TRJOXM-rBcMg"
17
+ data-option-zoom="10"
18
+ data-option-center="[2.35, 48.86]"
19
+ data-option-map-options='{"style":"mapbox://styles/mapbox/streets-v12"}'
20
+ class="h-96 w-full">
21
+ <div data-ref="container" class="h-full w-full"></div>
22
+ </div>
23
+ ```
24
+
25
+ ```js
26
+ import { registerComponent } from '@studiometa/js-toolkit';
27
+ import { MapboxMap } from '@studiometa/ui-mapbox';
28
+
29
+ registerComponent(MapboxMap);
30
+ ```
31
+
32
+ ```css
33
+ html.dark {
34
+ background-color: #222;
35
+ color: #eee;
36
+ }
37
+
38
+ body {
39
+ padding: 1rem;
40
+ }
41
+ ```
42
+
43
+ ## Markers and popups
44
+
45
+ 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.
46
+
47
+ ```twig
48
+ <link rel="stylesheet" href="https://esm.sh/mapbox-gl@3.13.0/dist/mapbox-gl.css" />
49
+
50
+ <div
51
+ data-component="MapboxMap"
52
+ data-option-access-token="pk.eyJ1IjoiYWdlbmNlc3R1ZGlvbWV0YSIsImEiOiJjbXM5NTBycHMwa2Z4MndxeW02YndscmQyIn0.UitMikKpq-TRJOXM-rBcMg"
53
+ data-option-zoom="12"
54
+ data-option-center="[2.35, 48.86]"
55
+ data-option-map-options='{"style":"mapbox://styles/mapbox/streets-v12"}'
56
+ class="h-96 w-full">
57
+ <div data-ref="container" class="h-full w-full"></div>
58
+
59
+ {# Marker with an attached popup, opened on click #}
60
+ <div hidden data-component="MapboxMarker" data-option-lng-lat="[2.35, 48.86]">
61
+ <div data-component="MapboxPopup">
62
+ <h3>Paris</h3>
63
+ <p>Capital of France</p>
64
+ </div>
65
+ </div>
66
+
67
+ {# Standalone popup, displayed directly on the map #}
68
+ <div hidden data-component="MapboxPopup" data-option-lng-lat="[2.29, 48.86]">
69
+ <p>Near the Eiffel Tower</p>
70
+ </div>
71
+ </div>
72
+ ```
73
+
74
+ ```js
75
+ import { registerComponents } from '@studiometa/js-toolkit';
76
+ import { MapboxMap, MapboxMarker, MapboxPopup } from '@studiometa/ui-mapbox';
77
+
78
+ // Register every component the markup uses.
79
+ registerComponents(MapboxMap, MapboxMarker, MapboxPopup);
80
+ ```
81
+
82
+ ```css
83
+ html.dark {
84
+ background-color: #222;
85
+ color: #eee;
86
+ }
87
+
88
+ body {
89
+ padding: 1rem;
90
+ }
91
+ ```
92
+
93
+ ## Navigation, geolocate and fullscreen controls
94
+
95
+ 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.
96
+
97
+ ```twig
98
+ <link rel="stylesheet" href="https://esm.sh/mapbox-gl@3.13.0/dist/mapbox-gl.css" />
99
+
100
+ {#
101
+ The `map-options` option forwards any mapbox-gl `Map` option. Here it sets a
102
+ specific style and a tilted, rotated camera (`pitch` + `bearing`) — the
103
+ navigation control's compass resets the bearing.
104
+ #}
105
+ <div
106
+ data-component="MapboxMap"
107
+ data-option-access-token="pk.eyJ1IjoiYWdlbmNlc3R1ZGlvbWV0YSIsImEiOiJjbXM5NTBycHMwa2Z4MndxeW02YndscmQyIn0.UitMikKpq-TRJOXM-rBcMg"
108
+ data-option-zoom="10"
109
+ data-option-center="[2.35, 48.86]"
110
+ data-option-map-options='{"style":"mapbox://styles/mapbox/streets-v12","pitch":45,"bearing":-17}'
111
+ class="h-96 w-full">
112
+ <div data-ref="container" class="h-full w-full"></div>
113
+
114
+ <div
115
+ hidden
116
+ data-component="MapboxNavigationControl"
117
+ data-option-position="top-right"
118
+ data-option-show-compass
119
+ data-option-show-zoom></div>
120
+
121
+ <div
122
+ hidden
123
+ data-component="MapboxGeolocateControl"
124
+ data-option-position="top-right"
125
+ data-option-track-user-location></div>
126
+
127
+ <div hidden data-component="MapboxFullscreenControl" data-option-position="top-right"></div>
128
+ </div>
129
+ ```
130
+
131
+ ```js
132
+ import { registerComponents } from '@studiometa/js-toolkit';
133
+ import {
134
+ MapboxMap,
135
+ MapboxNavigationControl,
136
+ MapboxGeolocateControl,
137
+ MapboxFullscreenControl,
138
+ } from '@studiometa/ui-mapbox';
139
+
140
+ // Register every component the markup uses.
141
+ registerComponents(
142
+ MapboxMap,
143
+ MapboxNavigationControl,
144
+ MapboxGeolocateControl,
145
+ MapboxFullscreenControl,
146
+ );
147
+ ```
148
+
149
+ ```css
150
+ html.dark {
151
+ background-color: #222;
152
+ color: #eee;
153
+ }
154
+
155
+ body {
156
+ padding: 1rem;
157
+ }
158
+ ```
159
+
160
+ ## Geocoder
161
+
162
+ 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.
163
+
164
+ With `add-to-map`, the geocoder is added to the map as a Mapbox control, overlaid on the map canvas:
165
+
166
+ ```html
167
+ <div
168
+ data-component="MapboxMap"
169
+ data-option-access-token="<YOUR_MAPBOX_ACCESS_TOKEN>"
170
+ data-option-zoom="5"
171
+ data-option-center="[2.35, 48.86]"
172
+ class="h-96 w-full">
173
+ <div data-ref="container" class="h-full w-full"></div>
174
+
175
+ <div
176
+ data-component="MapboxGeocoder"
177
+ data-option-add-to-map
178
+ data-option-options='{"placeholder": "Search a place…"}'></div>
179
+ </div>
180
+ ```
181
+
182
+ 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:
183
+
184
+ ```html
185
+ <div
186
+ data-component="MapboxMap"
187
+ data-option-access-token="<YOUR_MAPBOX_ACCESS_TOKEN>"
188
+ data-option-zoom="5"
189
+ data-option-center="[2.35, 48.86]"
190
+ class="h-96 w-full">
191
+ <!-- The search field renders here, above the map -->
192
+ <div
193
+ data-component="MapboxGeocoder"
194
+ data-option-options='{"placeholder": "Search a place…"}'></div>
195
+ <div data-ref="container" class="h-full w-full"></div>
196
+ </div>
197
+ ```
198
+
199
+ The geocoder uses the access token of the parent `MapboxMap`, unless it sets its own with `data-option-access-token`.
200
+
201
+ Do not put `hidden` on a `MapboxGeocoder` element. With autoloading, the geocoder loads when its element nears the viewport, and a hidden element never does.
202
+
203
+ The geocoder also works without a map. Outside a `MapboxMap`, set its `data-option-access-token` and listen to `map-result` to use the selected address, for example to submit a search form:
204
+
205
+ ```html
206
+ <div
207
+ data-component="MapboxGeocoder"
208
+ data-option-access-token="<YOUR_MAPBOX_ACCESS_TOKEN>"
209
+ data-option-options='{"placeholder": "Search a place…"}'></div>
210
+ ```
211
+
212
+ See [Standalone usage](js-api.md#standalone-usage) for a complete example.
213
+
214
+ ## Source and layer
215
+
216
+ 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/).
217
+
218
+ ```twig
219
+ <link rel="stylesheet" href="https://esm.sh/mapbox-gl@3.13.0/dist/mapbox-gl.css" />
220
+
221
+ <div
222
+ data-component="MapboxMap"
223
+ data-option-access-token="pk.eyJ1IjoiYWdlbmNlc3R1ZGlvbWV0YSIsImEiOiJjbXM5NTBycHMwa2Z4MndxeW02YndscmQyIn0.UitMikKpq-TRJOXM-rBcMg"
224
+ data-option-zoom="11"
225
+ data-option-center="[2.35, 48.86]"
226
+ data-option-map-options='{"style":"mapbox://styles/mapbox/streets-v12"}'
227
+ class="h-96 w-full">
228
+ <div data-ref="container" class="h-full w-full"></div>
229
+
230
+ {# A GeoJSON source describing a route across Paris #}
231
+ <div
232
+ hidden
233
+ data-component="MapboxSource"
234
+ data-option-id="route"
235
+ data-option-source='{
236
+ "type": "geojson",
237
+ "data": {
238
+ "type": "Feature",
239
+ "geometry": {
240
+ "type": "LineString",
241
+ "coordinates": [
242
+ [2.2945, 48.8584],
243
+ [2.3376, 48.8606],
244
+ [2.3499, 48.8530],
245
+ [2.3653, 48.8467]
246
+ ]
247
+ }
248
+ }
249
+ }'></div>
250
+
251
+ {# A line layer rendering the source #}
252
+ <div
253
+ hidden
254
+ data-component="MapboxLayer"
255
+ data-option-id="route-line"
256
+ data-option-layer='{
257
+ "type": "line",
258
+ "source": "route",
259
+ "layout": { "line-join": "round", "line-cap": "round" },
260
+ "paint": { "line-color": "#e11d48", "line-width": 5 }
261
+ }'></div>
262
+ </div>
263
+ ```
264
+
265
+ ```js
266
+ import { registerComponents } from '@studiometa/js-toolkit';
267
+ import { MapboxMap, MapboxSource, MapboxLayer } from '@studiometa/ui-mapbox';
268
+
269
+ // Register every component the markup uses.
270
+ registerComponents(MapboxMap, MapboxSource, MapboxLayer);
271
+ ```
272
+
273
+ ```css
274
+ html.dark {
275
+ background-color: #222;
276
+ color: #eee;
277
+ }
278
+
279
+ body {
280
+ padding: 1rem;
281
+ }
282
+ ```
283
+
284
+ ## Images
285
+
286
+ 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.
287
+
288
+ ```twig
289
+ <link rel="stylesheet" href="https://esm.sh/mapbox-gl@3.13.0/dist/mapbox-gl.css" />
290
+
291
+ <div
292
+ data-component="MapboxMap"
293
+ data-option-access-token="pk.eyJ1IjoiYWdlbmNlc3R1ZGlvbWV0YSIsImEiOiJjbXM5NTBycHMwa2Z4MndxeW02YndscmQyIn0.UitMikKpq-TRJOXM-rBcMg"
294
+ data-option-zoom="4"
295
+ data-option-center="[2.35, 48.86]"
296
+ data-option-map-options='{"style":"mapbox://styles/mapbox/streets-v12"}'
297
+ class="h-96 w-full">
298
+ <div data-ref="container" class="h-full w-full"></div>
299
+
300
+ {# Load several images at once into the map sprite #}
301
+ <div
302
+ hidden
303
+ data-component="MapboxImages"
304
+ data-option-sources='[
305
+ { "name": "cat", "url": "https://docs.mapbox.com/mapbox-gl-js/assets/cat.png" },
306
+ { "name": "dog", "url": "https://docs.mapbox.com/mapbox-gl-js/assets/dog.png" }
307
+ ]'></div>
308
+
309
+ {# Points carrying the icon name and label to use #}
310
+ <div
311
+ hidden
312
+ data-component="MapboxSource"
313
+ data-option-id="pets"
314
+ data-option-source='{
315
+ "type": "geojson",
316
+ "data": {
317
+ "type": "FeatureCollection",
318
+ "features": [
319
+ { "type": "Feature", "properties": { "icon": "cat", "label": "Cat" }, "geometry": { "type": "Point", "coordinates": [2.35, 48.86] } },
320
+ { "type": "Feature", "properties": { "icon": "dog", "label": "Dog" }, "geometry": { "type": "Point", "coordinates": [4.83, 45.76] } }
321
+ ]
322
+ }
323
+ }'></div>
324
+
325
+ {# A symbol layer rendering each point with its icon and a text label #}
326
+ <div
327
+ hidden
328
+ data-component="MapboxLayer"
329
+ data-option-id="pets-icons"
330
+ data-option-layer='{
331
+ "type": "symbol",
332
+ "source": "pets",
333
+ "layout": {
334
+ "icon-image": ["get", "icon"],
335
+ "icon-size": 0.15,
336
+ "icon-allow-overlap": true,
337
+ "text-field": ["get", "label"],
338
+ "text-offset": [0, 1.6],
339
+ "text-anchor": "top",
340
+ "text-size": 14
341
+ },
342
+ "paint": {
343
+ "text-halo-color": "#fff",
344
+ "text-halo-width": 1
345
+ }
346
+ }'></div>
347
+ </div>
348
+ ```
349
+
350
+ ```js
351
+ import { registerComponents } from '@studiometa/js-toolkit';
352
+ import { MapboxMap, MapboxImages, MapboxSource, MapboxLayer } from '@studiometa/ui-mapbox';
353
+
354
+ // Register every component the markup uses.
355
+ registerComponents(MapboxMap, MapboxImages, MapboxSource, MapboxLayer);
356
+ ```
357
+
358
+ ```css
359
+ html.dark {
360
+ background-color: #222;
361
+ color: #eee;
362
+ }
363
+
364
+ body {
365
+ padding: 1rem;
366
+ }
367
+ ```
368
+
369
+ ## Cluster
370
+
371
+ 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.
372
+
373
+ ```twig
374
+ <link rel="stylesheet" href="https://esm.sh/mapbox-gl@3.13.0/dist/mapbox-gl.css" />
375
+
376
+ {% set points = [
377
+ [2.3522, 48.8566], [2.2945, 48.8584], [2.3376, 48.8606], [2.3499, 48.853],
378
+ [2.3212, 48.8656], [4.8357, 45.764], [4.8467, 45.7578], [5.3698, 43.2965],
379
+ [5.38, 43.29], [-0.5792, 44.8378], [-1.5536, 47.2184], [3.0573, 50.6292],
380
+ [7.7521, 48.5734], [1.4442, 43.6047], [1.4535, 43.6108], [-4.4861, 48.3904],
381
+ [4.3872, 50.8503], [6.1432, 46.2044]
382
+ ] %}
383
+
384
+ <div
385
+ data-component="MapboxMap"
386
+ data-option-access-token="pk.eyJ1IjoiYWdlbmNlc3R1ZGlvbWV0YSIsImEiOiJjbXM5NTBycHMwa2Z4MndxeW02YndscmQyIn0.UitMikKpq-TRJOXM-rBcMg"
387
+ data-option-zoom="4"
388
+ data-option-center="[2.35, 48.86]"
389
+ data-option-map-options='{"style":"mapbox://styles/mapbox/streets-v12"}'
390
+ class="h-96 w-full">
391
+ <div data-ref="container" class="h-full w-full"></div>
392
+
393
+ {# The cluster derives its source from the MapboxClusterItems in its subtree.
394
+ Here they carry no visible list, so the wrapper is hidden — the same markup
395
+ would double as a sidebar in a StoreLocator. #}
396
+ <div
397
+ hidden
398
+ data-component="MapboxCluster"
399
+ data-option-cluster-radius="60"
400
+ data-option-clusters-paint='{ "circle-color": "#51bbd6", "circle-radius": 20 }'
401
+ data-option-unclustered-point-paint='{ "circle-color": "#f28cb1", "circle-radius": 6, "circle-stroke-width": 1, "circle-stroke-color": "#fff" }'>
402
+ <ul>
403
+ {% for point in points %}
404
+ <li
405
+ data-component="MapboxClusterItem"
406
+ data-option-id="p{{ loop.index }}"
407
+ data-option-lng-lat="{{ point|json_encode }}"></li>
408
+ {% endfor %}
409
+ </ul>
410
+ </div>
411
+ </div>
412
+ ```
413
+
414
+ ```js
415
+ import { registerComponents } from '@studiometa/js-toolkit';
416
+ import { MapboxMap, MapboxCluster, MapboxClusterItem } from '@studiometa/ui-mapbox';
417
+
418
+ registerComponents(MapboxMap, MapboxCluster, MapboxClusterItem);
419
+ ```
420
+
421
+ ```css
422
+ html.dark {
423
+ background-color: #222;
424
+ color: #eee;
425
+ }
426
+
427
+ body {
428
+ padding: 1rem;
429
+ }
430
+ ```
431
+
432
+ ### Items drive the source {#cluster-items}
433
+
434
+ 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:
435
+
436
+ ```html
437
+ <div hidden data-component="MapboxCluster" data-option-cluster-radius="60">
438
+ <ul>
439
+ <li
440
+ data-component="MapboxClusterItem"
441
+ data-option-id="a"
442
+ data-option-lng-lat="[2.35, 48.86]"></li>
443
+ <li
444
+ data-component="MapboxClusterItem"
445
+ data-option-id="b"
446
+ data-option-lng-lat="[2.29, 48.86]"></li>
447
+ <li
448
+ data-component="MapboxClusterItem"
449
+ data-option-id="c"
450
+ data-option-lng-lat="[-0.13, 51.51]"></li>
451
+ </ul>
452
+ </div>
453
+ ```
454
+
455
+ 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`](../StoreLocator/index.md) orchestrator.
456
+
457
+ ## Listening to map events
458
+
459
+ 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<ComponentName><EventName>` methods — for example `onMapboxMapMapClick` or `onMapboxMapMapLoad`.
460
+
461
+ ```js
462
+ import { Base, registerComponent } from '@studiometa/js-toolkit';
463
+ import { MapboxMap } from '@studiometa/ui-mapbox';
464
+
465
+ class App extends Base {
466
+ static config = {
467
+ name: 'App',
468
+ components: { MapboxMap },
469
+ };
470
+
471
+ onMapboxMapMapLoad({ payload: { map } }) {
472
+ console.log('Map loaded', map);
473
+ }
474
+
475
+ onMapboxMapMapClick({ payload: { event } }) {
476
+ console.log('Clicked at', event.lngLat);
477
+ }
478
+ }
479
+
480
+ registerComponent(App);
481
+ ```
@@ -0,0 +1,102 @@
1
+ # MapboxMap
2
+
3
+ The `MapboxMap` component and its family let you build [Mapbox GL](https://docs.mapbox.com/mapbox-gl-js/) maps declaratively, straight from your HTML, with [js-toolkit](https://js-toolkit.studiometa.dev/). A `MapboxMap` element owns the underlying Mapbox `Map` instance, and every other component (markers, popups, controls, sources, layers, images, clusters) is authored as a child element that registers itself against that map once it is loaded.
4
+
5
+ These components are published in the standalone [`@studiometa/ui-mapbox`](https://www.npmjs.com/package/@studiometa/ui-mapbox) package and replace the [`@studiometa/vue-mapbox-gl`](https://www.npmjs.com/package/@studiometa/vue-mapbox-gl) library. If you are coming from the Vue library, read the [migration guide](https://ui-v2.studiometa.dev/migration-guides/vue-mapbox-gl/).
6
+
7
+ ## Table of content
8
+
9
+ - [Examples](examples.md)
10
+ - [JS API](js-api.md)
11
+
12
+ ## Installation
13
+
14
+ Install the package alongside its `mapbox-gl` peer dependency. The [`@mapbox/mapbox-gl-geocoder`](https://github.com/mapbox/mapbox-gl-geocoder) package is only required if you use the [`MapboxGeocoder`](js-api.md#mapboxgeocoder) component.
15
+
16
+ ```bash
17
+ npm install @studiometa/ui-mapbox mapbox-gl
18
+
19
+ # Optional, only for the geocoder control
20
+ npm install @mapbox/mapbox-gl-geocoder
21
+ ```
22
+
23
+ The Mapbox GL stylesheet is required for the map, its controls and popups to render correctly. Add it to your page, either as a `<link>` tag pointing to the CDN or by importing it from the package with your bundler.
24
+
25
+ ```html
26
+ <link rel="stylesheet" href="https://api.mapbox.com/mapbox-gl-js/v3.13.0/mapbox-gl.css" />
27
+ ```
28
+
29
+ ```css
30
+ /* or, when using a bundler */
31
+ @import 'mapbox-gl/dist/mapbox-gl.css';
32
+ ```
33
+
34
+ You will also need a [Mapbox access token](https://docs.mapbox.com/help/getting-started/access-tokens/). Pass it to the `MapboxMap` component through the `access-token` option.
35
+
36
+ ## Usage
37
+
38
+ [Register](https://ui-v2.studiometa.dev/guide/usage/#registering-components) each component your page uses: a bare map with just a `container` needs only `MapboxMap`, and each marker, popup, control, source, layer, image or cluster you declare must be registered too. Registration order does not matter, because a child registered before its `MapboxMap` still wires up once the map connects.
39
+
40
+ Author the map with a root `MapboxMap` element holding a `container` ref, and give it a size through CSS.
41
+
42
+ ```js [app.js]
43
+ import { registerComponent } from '@studiometa/js-toolkit';
44
+ import { MapboxMap } from '@studiometa/ui-mapbox';
45
+
46
+ registerComponent(MapboxMap);
47
+ ```
48
+
49
+ ```html [index.html]
50
+ <div
51
+ data-component="MapboxMap"
52
+ data-option-access-token="<YOUR_MAPBOX_ACCESS_TOKEN>"
53
+ data-option-zoom="10"
54
+ data-option-center="[2.35, 48.86]"
55
+ class="h-96 w-full">
56
+ <div data-ref="container" class="h-full w-full"></div>
57
+ </div>
58
+ ```
59
+
60
+ ```css [app.css]
61
+ @import 'mapbox-gl/dist/mapbox-gl.css';
62
+ ```
63
+
64
+ `mapbox-gl` is a heavy dependency (~230&nbsp;kB gzipped, more with the geocoder), so the recommended default is to register the components as lazy manifest entries — see [Lazy loading](#lazy-loading) below.
65
+
66
+ ## Lazy loading
67
+
68
+ `mapbox-gl` is never in your main bundle: `MapboxMap` loads it with a dynamic `import()` when it mounts, and `MapboxMap` mounts only when the map nears the viewport, whether you register the class or a manifest entry. Registering the family as a [manifest](https://ui-v2.studiometa.dev/guide/autoloading/) rather than as classes also defers the component modules. A manifest entry is a lazy importer plus a mount strategy, so a component module loads only when an element on the page declares its token, and only when its strategy allows.
69
+
70
+ The package ships its own manifest, which is the shortest way to get all of it:
71
+
72
+ ```js
73
+ import { registerManifest } from '@studiometa/js-toolkit';
74
+ import { manifest } from '@studiometa/ui-mapbox/manifest';
75
+
76
+ registerManifest(manifest);
77
+ ```
78
+
79
+ Every component is also available at its own subpath (`@studiometa/ui-mapbox/<Component>`), whose default export is the component class, so a hand-written manifest can carry only the components you use. Each component is registered independently, so list every one you declare: deferring `MapboxMap` pulls in `mapbox-gl`, but a marker or a cluster is its own module and needs its own entry.
80
+
81
+ ```js
82
+ import { registerManifest } from '@studiometa/js-toolkit';
83
+
84
+ registerManifest({
85
+ MapboxMap: {
86
+ mountStrategy: 'visible',
87
+ load: () => import('@studiometa/ui-mapbox/MapboxMap'),
88
+ },
89
+ MapboxMarker: {
90
+ mountStrategy: 'eager',
91
+ load: () => import('@studiometa/ui-mapbox/MapboxMarker'),
92
+ },
93
+ MapboxPopup: {
94
+ mountStrategy: 'eager',
95
+ load: () => import('@studiometa/ui-mapbox/MapboxPopup'),
96
+ },
97
+ });
98
+ ```
99
+
100
+ The map renders, so `visible` holds the `mapbox-gl` import back until a map approaches the viewport. A marker renders nothing, so its element carries `hidden`, and a popup nested in it is hidden with it. A standalone popup shows its content until the map is ready, unless its element carries `hidden` too. A hidden element never intersects the viewport, so give markers and popups `eager`, which waits for nothing beyond the element being on the page. This is what the package manifest already does — see [Package defaults](https://ui-v2.studiometa.dev/guide/autoloading/#package-defaults).
101
+
102
+ Reach for a different strategy when it fits better — `idle`, `interaction`, `media:<query>` — and override any of them per element with `data-mount`. The [Autoloading](https://ui-v2.studiometa.dev/guide/autoloading/) guide lists all six.