Maps
On this page
phApp.map() draws an interactive map with markers and popups, for things like store locations or
devices on a site. Base maps switch between light and dark with the theme. It's built on MapLibre
5, with base maps that follow the light and dark theme.
Add ph-app-maps.js after ph-app.js on pages with a map. It's the largest optional script
(about 284 KB), so only add it where there's a map.
<script defer src="https://app.performancehub.co/assets/app-kit/v1/ph-app-maps.js"></script>
Usage


Figure 1: Store markers in the default, success and danger tones
<article class="ph-card ph-card--flush">
<header class="ph-card-header">
<div>
<h2 class="ph-card-title">Stores</h2>
<p class="ph-card-description">Orders this week</p>
</div>
</header>
<div id="stores"></div>
</article>
const stores = phApp.map('#stores', {
label: 'Store locations',
markers: [
{ lngLat: [147.2512, -33.1698], label: 'Ormsby Point', popup: 'Ormsby Point · 1,840 orders' },
{ lngLat: [147.2435, -33.18], label: 'Wattlebrook', popup: 'Wattlebrook · 990 orders', tone: 'success' },
{ lngLat: [147.2125, -33.1848], label: 'Harrow Bay', popup: 'Harrow Bay · offline since 9:40 am', tone: 'danger' },
],
});
stores.setMarkers(nextMarkers);
stores.fitToMarkers();
Without a center, the map fits itself to the markers.
Options
| Option | Default | What it does |
|---|---|---|
label | (required) | The map's accessible name |
markers | [] | The markers (see below) |
center | fit to the markers | [longitude, latitude] |
zoom | 14 with a center | The starting zoom |
height | 360 | Height in pixels |
cooperativeGestures | true | Scrolling the page doesn't zoom the map; zoom with Ctrl or ⌘ and scroll, or two fingers |
navigation | true | The zoom buttons |
styles | A light and a dark base map style | Base map style URLs: { light, dark }, or one URL |
onLoad | none | (map), when the base map has loaded |
mapOptions | none | Other MapLibre options |
Markers
| Field | What it does |
|---|---|
lngLat | [longitude, latitude] (longitude first) |
label | The marker's accessible name and tooltip |
popup | Text, or an element you've built, shown on click |
tone | 'success', 'warning', 'danger' or 'neutral'; blue without one |
onClick | (marker), when it's clicked |
phApp.map() returns { map, setMarkers(markers), fitToMarkers(), destroy() }, where map is the
MapLibre map.
Accessibility
- Markers are buttons named by their
label, so keyboard users can reach them and open popups. - Give the map a
labelthat says what it shows. - Put the same information in a list or table near the map; a map alone isn't enough for everyone.
React
import { MapView } from 'ph-app-kit-react/maps';
<MapView label="Store locations" markers={stores.map((store) => ({ lngLat: store.lngLat, label: store.name, popup: <StoreCard store={store} /> }))} />
Guidelines
- Use a map when where things are matters. For a ranking of places, use a bar chart.
- Colour markers by status with the tones, and explain the colours nearby.
- Popups hold a line or two: the name, a key number and a link.
- Base maps load from the internet. On networks that block it, markers still show on an empty map.