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

A map of stores with markersA map of stores with markers

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

OptionDefaultWhat it does
label(required)The map's accessible name
markers[]The markers (see below)
centerfit to the markers[longitude, latitude]
zoom14 with a centerThe starting zoom
height360Height in pixels
cooperativeGesturestrueScrolling the page doesn't zoom the map; zoom with Ctrl or ⌘ and scroll, or two fingers
navigationtrueThe zoom buttons
stylesA light and a dark base map styleBase map style URLs: { light, dark }, or one URL
onLoadnone(map), when the base map has loaded
mapOptionsnoneOther MapLibre options

Markers

FieldWhat it does
lngLat[longitude, latitude] (longitude first)
labelThe marker's accessible name and tooltip
popupText, 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 label that 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.