---
url: /migration-guides/vue-mapbox-gl.md
---
# @studiometa/vue-mapbox-gl → @studiometa/ui-mapbox
This guide helps you migrate from the Vue 3 library [`@studiometa/vue-mapbox-gl`](https://www.npmjs.com/package/@studiometa/vue-mapbox-gl) to the [js-toolkit](https://js-toolkit.studiometa.dev/) components published in [`@studiometa/ui-mapbox`](https://www.npmjs.com/package/@studiometa/ui-mapbox).
\[\[toc]]
## Why migrate
`@studiometa/ui-mapbox` re-implements the Mapbox GL components on top of [js-toolkit](https://js-toolkit.studiometa.dev/) instead of Vue. The main benefits are:
* **No Vue dependency** — the components are plain js-toolkit classes bound to the DOM through `data-component` attributes. You do not need Vue in your project to render a map.
* **Lighter for simple maps** — you ship the map logic and Mapbox GL, without a framework runtime, which keeps the footprint small for mostly-static maps.
* **Server-rendered friendly** — the map is authored as regular HTML and enhanced in place, which fits Twig/Blade/Nunjucks templates naturally.
The trade-off is that component options are **not reactive** (see [Reactivity caveat](#reactivity-caveat)). If your map relies heavily on reactive props driven by application state, weigh that difference before migrating.
## Install and setup
Replace the Vue library with the js-toolkit package and its peers.
```bash
npm remove @studiometa/vue-mapbox-gl
npm install @studiometa/ui-mapbox mapbox-gl
# Optional, only if you use the geocoder
npm install @mapbox/mapbox-gl-geocoder
```
The Mapbox GL stylesheet is still required. Keep importing it as before:
```css
@import 'mapbox-gl/dist/mapbox-gl.css';
```
Instead of registering the components on a Vue app, register them with js-toolkit. Every component is self-registering — `MapboxMap` no longer declares its children, so each one must be registered with [`registerComponent`](https://js-toolkit.studiometa.dev/api/helpers/registerComponent.html). Register only the ones you use — a bare map needs only `MapboxMap`, but every marker, control, source or cluster you declare needs its own registration. Registration order does not matter, because a child registered before its `MapboxMap` still wires up once the map connects. Because `mapbox-gl` is heavy (~230 kB gzipped), the recommended default is to lazy-register each component with js-toolkit's [`importWhen*` helpers](https://js-toolkit.studiometa.dev/api/helpers/importWhenVisible.html) and the per-component subpaths (each subpath's default export is the component class):
```js
import { registerComponent, importWhenVisible } from '@studiometa/js-toolkit';
// Register only the components your page uses; order doesn't matter.
registerComponent(importWhenVisible(() => import('@studiometa/ui-mapbox/MapboxMap'), 'MapboxMap'));
registerComponent(
importWhenVisible(() => import('@studiometa/ui-mapbox/MapboxMarker'), 'MapboxMarker'),
);
registerComponent(
importWhenVisible(() => import('@studiometa/ui-mapbox/MapboxPopup'), 'MapboxPopup'),
);
```
## Component mapping
Most Vue components have a same-named js-toolkit equivalent, which you author as `data-component` elements nested inside a `MapboxMap` instead of Vue templates. The clustering and store-locator components are the exception — they were re-architected around a new `MapboxClusterItem`, detailed below the table.
| `@studiometa/vue-mapbox-gl` | `@studiometa/ui-mapbox` | Notes |
| --------------------------- | ------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `MapboxMap` | `MapboxMap` | Root component, owns the map instance. |
| `MapboxMarker` | `MapboxMarker` | |
| `MapboxPopup` | `MapboxPopup` | Content comes from the element's inner HTML. |
| `MapboxNavigationControl` | `MapboxNavigationControl` | |
| `MapboxGeolocateControl` | `MapboxGeolocateControl` | |
| `MapboxFullscreenControl` | `MapboxFullscreenControl` | Ported. |
| `MapboxGeocoder` | `MapboxGeocoder` | Needs the optional `@mapbox/mapbox-gl-geocoder`. |
| `MapboxSource` | `MapboxSource` | Ported. |
| `MapboxLayer` | `MapboxLayer` | |
| `MapboxImage` | `MapboxImage` | Ported. |
| `MapboxImages` | `MapboxImages` | Ported. |
| `MapboxCluster` | `MapboxCluster` | Re-architected — the source is derived from child `MapboxClusterItem`s, not a `data` prop. See [below](#mapboxcluster-data). |
| — | `MapboxClusterItem` | **New** — a rendered cluster entry (list item + map feature). See [below](#mapboxcluster-data). |
| `StoreLocator` | `StoreLocator` | Re-implemented as a thin orchestrator over `MapboxMap` + `MapboxCluster` + `MapboxClusterItem`s. See its [documentation](/reference/items/StoreLocator/). |
| `VueScroller` | — | No equivalent needed — the store list is a plain scrollable element, styled with CSS. |
::: tip StoreLocator is now available
`StoreLocator` has been re-implemented as a thin **orchestrator** over a `MapboxMap` + `MapboxCluster` + `MapboxClusterItem`s (plus an optional `MapboxGeocoder`). The single-purpose `StoreLocatorItem` class of the Vue library is gone: each store is a `MapboxClusterItem` that is at once the sidebar list entry and the map feature. The `VueScroller` helper has no equivalent — the list is a plain scrollable element you style with CSS. See the [`StoreLocator` documentation](/reference/items/StoreLocator/).
:::
## API translation
### Props → options
Vue props become js-toolkit `data-option-*` attributes on the corresponding element, in kebab-case. Objects and arrays are passed as JSON strings.
```html
```
```html
```
The js-toolkit `MapboxMap` exposes a focused set of options (`access-token`, `zoom`, `center`) and forwards them to the Mapbox `Map` constructor, so any other serializable map option can be added as a `data-option-*` attribute. See the [full options reference](/reference/items/MapboxMap/js-api).
A key structural difference: the map needs an explicit **`container` ref** child (`
`), and child components that only act as declarative definitions (markers, popups, controls, sources, layers, images, clusters) are wrapped in a `hidden` element so they do not take part in the document flow.
### Event listeners → emitted events
The Vue library re-emits Mapbox map events prefixed with `mb-` (e.g. `@mb-load`, `@mb-click`). The js-toolkit components use the `map-` prefix instead. Listen to the emitted events from a parent component with `on` handler methods.
| Vue listener | js-toolkit emitted event | Parent handler method |
| ----------------------------- | ------------------------ | -------------------------------- |
| `@mb-load` (map loaded) | `map-load` | `onMapboxMapMapLoad` |
| `@mb-click` | `map-click` | `onMapboxMapMapClick` |
| `@mb-moveend` | `map-moveend` | `onMapboxMapMapMoveend` |
| `@mb-zoomend` | `map-zoomend` | `onMapboxMapMapZoomend` |
| `MapboxCluster` cluster click | `map-cluster-click` | `onMapboxClusterMapClusterClick` |
| `MapboxCluster` feature click | `map-item-click` | `onMapboxClusterMapItemClick` |
Every public event uses the `map-` prefix. The `MapboxMap` component re-emits the full list of Mapbox map events; `MapboxCluster` emits `map-cluster-click`, `map-item-click` (an unclustered point, resolved back to the registered `MapboxClusterItem` behind it) and `map-update` (the item set changed); `MapboxGeocoder` emits `map-result`; `MapboxImage` and `MapboxImages` emit `map-ready`; map children emit `map-error` when guarded lifecycle work fails; and `StoreLocator` emits `map-select`, `map-deselect` and `map-filter`. See each component's events in the [JS API](/reference/items/MapboxMap/js-api).
```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);
}
}
createApp(App);
```
### Slots → DOM children and refs
Vue slots become real DOM children:
* The `MapboxMap` default slot content becomes child elements inside the `MapboxMap` element. The map canvas target moves from an internal ref to an explicit `
`.
* The `MapboxMarker` / `MapboxPopup` content (Vue `default` / `popup` slots) becomes the inner HTML of the corresponding element. A popup nested inside a marker is attached to it automatically.
```html
Paris
```
```html
Paris
```
### MapboxCluster data {#mapboxcluster-data}
In the Vue library, the `MapboxCluster` `data` prop accepted a URL string or an inline GeoJSON object. The re-architected `MapboxCluster` has **no `data` option at all**: it is a pure source driver whose features *are* its rendered children. Each point is a `MapboxClusterItem` element (living in the cluster's subtree, typically a sidebar list `
`) that self-registers with its closest `MapboxCluster`; the cluster derives its clustered GeoJSON `FeatureCollection` from that registry and rebuilds it (debounced) whenever items mount or unmount. The same markup is at once the sidebar list and the map source.
```html
```
To load points from a server, render the `MapboxClusterItem` list from your backend (or swap it with a [`Fetch`](/reference/items/Fetch/)): mounting/terminating the items drives the map data, no `data` URL needed. For one-off imperative control you can still push a `FeatureCollection` straight to the source with the cluster's `setData(data)` method, but the registry remains the source of truth and the next item change overwrites it. See the [`MapboxCluster` reference](/reference/items/MapboxMap/js-api#mapboxcluster) and the [`StoreLocator`](/reference/items/StoreLocator/) built on top of it.
## Reactivity caveat
In `@studiometa/vue-mapbox-gl`, changing a prop updated the map reactively (moving the center, updating the source data, and so on). In `@studiometa/ui-mapbox`, **options are read once at mount and are not reactive**.
To update the map after mount, call the underlying Mapbox objects directly through the component instances:
```js
import { getInstance } from '@studiometa/js-toolkit';
import { MapboxMap } from '@studiometa/ui-mapbox';
const mapboxMap = getInstance(element, MapboxMap);
// Move the map
mapboxMap.map.setCenter([2.35, 48.86]);
mapboxMap.map.setZoom(12);
// Update a source
mapboxMap.map.getSource('points').setData(newGeoJson);
```
Each component exposes its Mapbox object (`map`, `marker`, `popup`, `control`, …). See the [JS API](/reference/items/MapboxMap/js-api#reactivity-and-updates) for the full list.
Two things the new lifecycle now handles for you, which the Vue library did not:
* **Switching the base style keeps your layers.** Calling `map.setStyle(…)` wipes every source, layer and sprite, but each declarative child re-injects its contribution on the map's `style.load`, so your sources, layers, images and clusters survive a base-style change (resolving [`vue-mapbox-gl` #248](https://github.com/studiometa/vue-mapbox-gl/issues/248)). You no longer need to re-declare data after a style switch.
* **Async ergonomics are internal.** Children resolve their parent map, wait for it to load, adopt or re-add resources across `Fetch` swaps and map remounts, and load the geocoder module on demand — all inside the shared base class, so you author plain declarative markup instead of orchestrating imperative `map.on('load', …)` wiring.
## Before / after
A complete map with a marker and an attached popup.
**Before — `@studiometa/vue-mapbox-gl`:**
```vue
Paris
Capital of France
```
**After — `@studiometa/ui-mapbox`:**
```html
Paris
Capital of France
```
```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] }) {
// former @mb-load handler
}
}
createApp(App);
```
---
---
url: /reference/items/Frame/js-api/abstract-frame-trigger.md
---
# AbstractFrameTrigger
## Options
### `requestInit`
* Type: `RequestInit`
* Default: `{}`
Customizes the options for the fetch request.
### `headers`
* Type: `Record`
* Default: `{}`
Adds custom headers to the fetch request. The headers merge with any `$options.requestInit.headers` already defined.
## Getters
### `url`
* Return: `URL`
* Default: `this.$el.href` or `this.$el.action` depending on the type of the root element
### `requestInit`
* Return: `RequestInit`
* Default: the `requestInit` and `headers` options merged
## Methods
### `trigger`
* Return: `Promise`
This method will be called by components extending the `AbstractFrameTrigger` to notify its parent `Frame` to fetch content.
## Emits
### `frame-trigger`
* Parameters:
* `url` (`URL`): the value returned by the `url` getter
* `requestInit` (`RequestInit`): the value returned by the `requestInit` getter
Emitted from the [`trigger` method](#trigger), when the component needs a request to be made by its parent `Frame` component.
### `frame-fetch-before`
* Parameters:
* `url` (`URL`): the URL requested
* `requestInit` (`RequestInit`): options for the fetch function
Emitted before the request starts.
### `frame-fetch`
* Parameters:
* `url` (`URL`): the URL requested
* `requestInit` (`RequestInit`): options for the fetch function
Emitted when the request starts.
### `frame-fetch-after`
* Parameters:
* `url` (`URL`): the URL requested
* `requestInit` (`RequestInit`): options for the fetch function
* `content` (`string | Error`): the content of the request if successful, an error otherwise
Emitted after the fetch request, be it successful or not. The third parameter can be either the content of the response or an error instance.
### `frame-content`
* Parameters:
* `url` (`URL`): the URL requested
* `requestInit` (`RequestInit`): options for the fetch function
* `content` (`string`): the content of the response
Emitted when the content of the request has been successfully received, but before its insertion in the current page.
### `frame-content-after`
* Parameters:
* `url` (`URL`): the URL requested
* `requestInit` (`RequestInit`): options for the fetch function
* `content` (`string`): the content of the response
Emitted after each `FrameTarget` component has received and updated its content, but before the final update on the root of the application which scan the updated content for components to mount.
### `frame-error`
* Parameters:
* `url` (`URL`): the URL requested
* `requestInit` (`RequestInit`): options for the fetch function
* `error` (`Error`): a fetch error
Emitted when the fetch request or the update of the content throw an error.
---
---
url: /reference/items/Accordion.md
---
# Accordion
::: warning Legacy component
`Accordion` remains available for backward compatibility. Use [`Disclosure` and `DisclosureGroup`](/reference/items/Disclosure/) for new work: they provide accessible `hidden`/`inert` state, independent dynamic child registration, nested groups and composable transitions without changing this legacy API.
:::
## Usage
After you install the [package](/guide/installation/), include the template in your project:
```js
import { registerComponent } from '@studiometa/js-toolkit';
import { Accordion } from '@studiometa/ui';
registerComponent(Accordion);
```
```twig{16}
{% set items = [
{
title: 'Title #1',
content: 'Content #1'
},
{
title: 'Title #2',
content: 'Content #2'
},
{
title: 'Title #3',
content: 'Content #3'
}
] %}
{% include '@ui/Accordion/Accordion.twig' with { items: items } %}
```
---
---
url: /reference/items/Accordion/anatomy.md
---
# Anatomy
`Accordion` is a compound component: a root orchestrates one or more `AccordionItem` children, each wiring its parts through `data-ref` attributes. Use this map to see which parts exist and how they nest.
## Structure
```
Accordion data-component="Accordion"
└─ AccordionItem (× n) data-component="AccordionItem"
├─ button [data-ref="btn"] the toggle, controls the panel
└─ container [data-ref="container"] the collapsible wrapper
└─ content [data-ref="content"] the panel content
```
## Parts
| Part | Selector | Required | Role |
| --- | --- | --- | --- |
| Root | `data-component="Accordion"` | Yes | Groups the items, handles `autoclose`, forwards the shared `item` options. |
| Item | `data-component="AccordionItem"` | Yes (× n) | A single expandable section. Holds the `isOpen` and `styles` options. |
| Trigger | `data-ref="btn"` | Yes | The `