@studiometa/ui-mapbox

Vanilla @studiometa/js-toolkit components to build Mapbox GL maps declaratively.

Installation

Install the package along with its mapbox-gl peer dependency:

npm install @studiometa/ui-mapbox mapbox-gl

The geocoder component relies on the optional @mapbox/mapbox-gl-geocoder peer dependency, install it only if you need it:

npm install @mapbox/mapbox-gl-geocoder

Usage

Register each component your page uses: each one registers independently and resolves its parent map on its own. mapbox-gl is heavy (~230 kB gzipped), so the recommended default is to lazy-register each component with js-toolkit's importWhen* helpers and the per-component subpaths (each subpath's default export is the component class), keeping the dependency out of your main bundle until a map is actually on the page:

import { registerComponents, importWhenVisible } from '@studiometa/js-toolkit';

// Register only the components your page uses; order doesn't matter.
registerComponents(
  importWhenVisible(() => import('@studiometa/ui-mapbox/MapboxMap'), 'MapboxMap'),
  importWhenVisible(() => import('@studiometa/ui-mapbox/MapboxMarker'), 'MapboxMarker'),
  importWhenVisible(() => import('@studiometa/ui-mapbox/MapboxPopup'), 'MapboxPopup'),
);

Other triggers are available too — importWhenIdle, importOnInteraction and importOnMediaQuery — see the importWhen* helper docs. Then author the map declaratively in your markup:

<div
  data-component="MapboxMap"
  data-option-access-token="pk.your-access-token"
  data-option-zoom="10"
  data-option-center="[2.3522, 48.8566]">
  <div data-ref="container" class="h-96 w-full"></div>

  <div hidden data-component="MapboxMarker" data-option-lng-lat="[2.3522, 48.8566]"></div>
</div>

If you do not need code-splitting, register eagerly instead — each component is exported by name from the package:

import { registerComponent } from '@studiometa/js-toolkit';
import { MapboxMap } from '@studiometa/ui-mapbox';

registerComponent(MapboxMap);

Do not forget to include the mapbox-gl stylesheet so the map renders correctly.

Providing mapbox-gl

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 the dependency stays out of your main bundle until it is needed. You never have to configure anything for the default to work — just keep mapbox-gl installed.

When you need to control which mapbox-gl the components use — a specific version, a self-hosted build (e.g. 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:

import mapboxgl from 'mapbox-gl';
import { provideMapboxGl, provideMapboxGeocoder } from '@studiometa/ui-mapbox';

provideMapboxGl(mapboxgl);

// Optional: inject the geocoder control constructor as well.
import MapboxGeocoder from '@mapbox/mapbox-gl-geocoder';
provideMapboxGeocoder(MapboxGeocoder);

Once provided, @studiometa/ui-mapbox never imports mapbox-gl by specifier — it uses the instance you handed it. resolveMapboxGl() / resolveMapboxGeocoder() are also exported if you want to trigger (and await) resolution yourself, for example to preload the module.

Heads up to ui.studiometa.dev for the full documentation.

Contributing

Please read the contribution docs.