---
url: /reference/items/StoreLocator.md
---
# StoreLocator
The `StoreLocator` component adds a "find a store near you" experience on top of a [`MapboxMap`](/reference/items/MapboxMap/). It is a thin **orchestrator**: it owns no map rendering and no item registry of its own. It wraps a `MapboxMap` containing a [`MapboxCluster`](/reference/items/MapboxMap/js-api#cluster) — the declarative clustered map **and** list source driver, whose [`MapboxClusterItem`](/reference/items/MapboxMap/js-api#mapboxclusteritem)s are the sidebar entries — plus an optional [`MapboxGeocoder`](/reference/items/MapboxMap/js-api#mapboxgeocoder) (address search), and layers the search UX on top: selection, viewport filtering and address search. Everything is authored declaratively from your HTML with [js-toolkit](https://js-toolkit.studiometa.dev/).
It is part of the [`@studiometa/ui-mapbox`](https://www.npmjs.com/package/@studiometa/ui-mapbox) package, alongside the rest of the [`MapboxMap` family](/reference/items/MapboxMap/).
## Cluster vs. orchestrator
The responsibilities are split in two:
* The **`MapboxCluster`** is a pure source driver. Its `MapboxClusterItem`s self-register, and it derives a clustered GeoJSON source from that registry (the map data), handles the click-to-zoom on clusters, and reports a click on an unclustered point through a `map-item-click` event. Used on its own it renders a working clustered map + list, but it never selects, flies, filters by viewport or opens popups.
* The **`StoreLocator`** wraps such a cluster and adds exactly those search-UX concerns: it selects items (fly-to, `active` styling, popup), filters and sorts the list on every map move, wires the geocoder, and re-frames the map on item-set changes.
## The three-state model
Each store has three independent states, each with its own source of truth. Keeping them separate is what makes the orchestrator predictable — panning the map never rebuilds the map data, and updating the item set never fights with the current viewport.
| State | Source of truth | Owner | Drives | Recomputed on |
| -------------- | ------------------------------------------ | --------------- | --------------------------------------------------- | -------------------- |
| **Registered** | the item exists in the DOM | `MapboxCluster` | the **map data** (markers/clusters) | item-set change only |
| **In bounds** | the item's `lngLat` is inside the viewport | `StoreLocator` | **list visibility + distance sort** only | every map `moveend` |
| **Selected** | the chosen item | `StoreLocator` | fly-to, popup, `active` styling, `map-select` event | selection |
Because the map data is derived only from the cluster's registered items, swapping the list (for instance through a [`Fetch`](/reference/items/Fetch/)) updates both the list **and** the map at once: the cluster re-derives its source and emits a `map-update`, and the orchestrator re-fits and re-filters in response. See the [faceted example](./examples#faceted-list).
## Composability
The `StoreLocator` emits events and reflects state as data-attributes on each `MapboxClusterItem`; it makes no decision about how a selected store is presented beyond the built-in popup. The [examples](./examples.md) use a [`Dialog`](/reference/items/Dialog/) drawer as the detail panel, but a static `aside` would work just as well — wire whichever you like to the [`map-select`](./js-api#map-select) event.
## Table of content
* [Examples](./examples.md)
* [JS API](./js-api.md)
## Installation
The component ships with the `@studiometa/ui-mapbox` package. Install it alongside its `mapbox-gl` peer dependency, exactly like the rest of the [`MapboxMap` family](/reference/items/MapboxMap/#installation).
```bash
npm install @studiometa/ui-mapbox mapbox-gl
```
The [Mapbox GL stylesheet](/reference/items/MapboxMap/#installation) and a [Mapbox access token](https://docs.mapbox.com/help/getting-started/access-tokens/) are required, just like for a plain map.
## Usage
The `StoreLocator` declares no child components — `StoreLocator`, `MapboxMap`, `MapboxCluster`, `MapboxClusterItem` and the optional `MapboxGeocoder` are each [registered](/guide/usage/#registering-components) independently and mount on their own; the orchestrator then discovers them in its subtree once mounted. As with a plain map, 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), keeping the heavy `mapbox-gl` dependency out of your main bundle until the store locator is on the page.
Because a `MapboxClusterItem` resolves its cluster and the cluster resolves its map through the closest matching ancestor, the DOM nests them: the `MapboxCluster` wraps the sidebar list of `MapboxClusterItem`s **inside** the `MapboxMap`, next to the map container. The `StoreLocator` wraps the map. The cluster carries **no** authored data — it derives its source from the registered items.
::: code-group
```js [app.js]
import { registerComponents, importWhenVisible } from '@studiometa/js-toolkit';
// Register only the components your page uses; order doesn't matter.
registerComponents(
importWhenVisible(() => import('@studiometa/ui-mapbox/StoreLocator'), 'StoreLocator'),
importWhenVisible(() => import('@studiometa/ui-mapbox/MapboxMap'), 'MapboxMap'),
importWhenVisible(() => import('@studiometa/ui-mapbox/MapboxCluster'), 'MapboxCluster'),
importWhenVisible(() => import('@studiometa/ui-mapbox/MapboxClusterItem'), 'MapboxClusterItem'),
);
```
```html [index.html]
```
```css [app.css]
@import 'mapbox-gl/dist/mapbox-gl.css';
/* List-visibility contract: hide items outside the current viewport. */
[data-component='MapboxClusterItem']:not([data-in-bounds]) {
display: none;
}
/* Selected-item contract. */
[data-component='MapboxClusterItem'][data-active] {
/* highlight the active store */
}
```
:::
Clicking anywhere in a `MapboxClusterItem` selects it (the orchestrator delegates the click on its root), and clicking an unclustered pin on the map selects the matching item too. The styling contract is entirely data-attribute driven: `data-in-bounds` toggles list visibility, `data-active` (plus `aria-current="true"`) marks the selected item. See the [styling contract](./js-api#styling-contract) for details.
## Lazy loading
Registering the family pulls in `MapboxMap` and its heavy `mapbox-gl` dependency (~230 kB gzipped). Register it lazily so it is code-split into its own chunk and only loaded when the locator is on the page, using the same [`importWhen*` helpers](https://js-toolkit.studiometa.dev/api/helpers/importWhenVisible.html) as the rest of the [`MapboxMap` family](/reference/items/MapboxMap/#lazy-loading):
```js
import { registerComponent, importWhenVisible } from '@studiometa/js-toolkit';
registerComponent(
importWhenVisible(() => import('@studiometa/ui-mapbox/StoreLocator'), 'StoreLocator'),
);
```
When lazy-loading only the `StoreLocator` subpath, remember to register the `MapboxMap`, `MapboxCluster` and `MapboxClusterItem` it orchestrates too (each is available at its own subpath, whose default export is the component class, so a dynamic import needs no destructuring).
`importWhenIdle`, `importOnInteraction` and `importOnMediaQuery` are available too — see the [MapboxMap lazy-loading note](/reference/items/MapboxMap/#lazy-loading).