---
url: /reference/items/StoreLocator/js-api.md
---
# JS API
The store locator is an **orchestrator** built on the [`MapboxMap` family](/reference/items/MapboxMap/js-api):
* `StoreLocator` — the coordinator, wrapping a [`MapboxMap`](/reference/items/MapboxMap/js-api#map) that contains a [`MapboxCluster`](/reference/items/MapboxMap/js-api#cluster).
* [`MapboxClusterItem`](/reference/items/MapboxMap/js-api#mapboxclusteritem) — a single store entry; it registers with the cluster (the owner of the item registry), and the orchestrator reads and drives it. There is **no** dedicated store-item class.
The `StoreLocator` declares no child components, so nothing is ever double-mounted. [Register](/guide/usage/#registering-components) `StoreLocator`, `MapboxMap`, `MapboxCluster` and `MapboxClusterItem` each independently — ideally behind a lazy [`importWhen*` helper](https://js-toolkit.studiometa.dev/api/helpers/importWhenVisible.html) (see [Lazy loading](/reference/items/MapboxMap/#lazy-loading)). The orchestrator discovers them in its subtree with `$query` once mounted, retrying a few ticks for asynchronously-mounted children (the geocoder lazy-imports its module).
To change the store set after mount, change the DOM of the list (add/remove `MapboxClusterItem` elements): the cluster re-derives the map data and emits a `map-update`, and the orchestrator re-fits and re-filters automatically.
## StoreLocator
The coordinator. It owns no map rendering and no registry: the `MapboxCluster` derives the GeoJSON source from its registered `MapboxClusterItem`s, and the orchestrator reads that item set to filter and sort the list on every map move, wire the geocoder, re-frame the map on item-set changes, and handle selection.
### Options
#### `item-zoom-level`
* Type: `Number`
* Default: `14`
The zoom level the map flies to when a store is selected.
#### `no-sort`
* Type: `Boolean`
* Default: `false`
Disable the distance sort. Sorting is on by default, reordering the in-view items nearest-first on every map move, so add `data-option-no-sort` to turn it off.
#### `fit-on-update`
* Type: `Boolean`
* Default: `false`
Fit the map bounds to the whole item set whenever it changes (on load and on any add/remove of items).
#### `popup-options`
* Type: `Object`
* Default: `{}`
Options forwarded to the `mapboxgl.Popup` opened on selection.
```html {3}
...
```
### Getters
#### `isLoaded`
* Type: `boolean`
Whether the underlying map has finished loading (a public field, not a getter).
#### `mapboxMap`
* Type: `MapboxMap`
The child `MapboxMap` component.
#### `map`
* Type: `mapboxgl.Map`
The underlying Mapbox `Map` instance. Only valid once the map has loaded.
#### `cluster`
* Type: `MapboxCluster | undefined`
The child `MapboxCluster` (the item registry + map data source).
#### `geocoder`
* Type: `MapboxGeocoder | undefined`
The optional child `MapboxGeocoder`.
#### `items`
* Type: `MapboxClusterItem[]`
The registered items, read from the cluster (their single source of truth).
### Methods
#### `selectItem(item)`
* Arguments: `MapboxClusterItem`
Select a store: deactivate the previous one, fly the map to the item at `item-zoom-level`, open a popup from the item's [`popupContent`](/reference/items/MapboxMap/js-api#mapboxclusteritem), mark it active (`data-active` + `aria-current="true"`) and emit [`map-select`](#map-select). Called automatically on a sidebar click (delegated on the root), on the cluster's `map-item-click` (an unclustered pin), and available for you to call directly.
#### `deselect()`
Clear the current selection, close the popup, remove the active state and emit [`map-deselect`](#map-deselect).
### Events
#### `map-select`
Emitted when a store is selected, with the selected `MapboxClusterItem` instance. Wire your detail panel here.
```js
onStoreLocatorMapSelect({ args: [item] }) {
// item.id, item.lngLat, item.$el …
}
```
#### `map-deselect`
Emitted when the selection is cleared through [`deselect()`](#deselect).
#### `map-filter`
Emitted whenever the in-view list is recomputed (on every map `moveend` and after an item-set change), with the array of in-view items in display order (nearest-first unless `no-sort` is set).
```js
onStoreLocatorMapFilter({ args: [items] }) {
// e.g. update a "N stores in view" counter
}
```
## Store entries: `MapboxClusterItem`
A single store entry is a [`MapboxClusterItem`](/reference/items/MapboxMap/js-api#mapboxclusteritem). It registers with the closest `MapboxCluster`, exposes `id`, `lngLat`, `properties` and `popupContent`, and reflects its state through `setInBounds`/`setActive` (driven by the orchestrator). Refer to its [reference](/reference/items/MapboxMap/js-api#mapboxclusteritem) for the full API. The orchestrator itself never reintroduces a separate item class — it drives the cluster's items.
## Styling contract {#styling-contract}
The orchestrator never styles anything: it only reflects state as attributes on each `MapboxClusterItem`. You own the CSS.
| Attribute | Meaning | Typical CSS |
| ------------------------------ | -------------------------------------------------------------- | ------------------------------------------------------------------------------ |
| `data-in-bounds` | The item is inside the current map viewport (list visibility). | `[data-component='MapboxClusterItem']:not([data-in-bounds]) { display: none }` |
| `data-active` + `aria-current` | The item is the selected one. | `[data-component='MapboxClusterItem'][data-active] { /* highlight */ }` |
```css
/* Hide out-of-view stores from the list. */
[data-component='MapboxClusterItem']:not([data-in-bounds]) {
display: none;
}
/* Highlight the selected store. */
[data-component='MapboxClusterItem'][data-active] {
background-color: #ecfdf5;
}
```