Appearance
Developer Guide
Welcome to the Mapsted Maps JavaScript API developer guide. Each entry below ships with a live demo — expand an accordion to run the snippet against the public sandbox without leaving the page.
▶ Try it live
Every guide entry below ships with a runnable demo — expand any accordion to run the snippet inline against a live map. Or open the full Sandbox playground ↗ (also in the top nav): a Monaco-backed editor where you can edit the code, swap properties, wire events, and copy a shareable URL.
How-to Guides
Step-by-step instructions for specific tasks. Each entry's accordion lazy-loads its embed iframe — the API only boots when you expand the demo, so the page stays fast even with every accordion shown.
Select an entity programmatically — wire the select event so any tap logs the live entityId.
Highlight a specific point of interest, room, or amenity from your own application logic — without requiring the user to tap the map themselves. Powers search-result highlighting, guided tours, and accessibility workflows.
Customize popups — register an HTML template that applies to every entity.
Replace the built-in popup with your own HTML, supplied per-entity or as a fallback for all entities via setEntityDefaults.
Add custom markers — apply a red-pulse default marker to every entity on the map.
Override the default Mapsted appearance for entities, coordinates, and CMS map-overlay regions. The demo below uses setEntityDefaults so the override applies to every entity without a hard-coded entityId.
Use overlay markers — apply a visible default marker to every entity.
Map overlay markers attach to CMS-provisioned regions. The sandbox demo below uses setEntityDefaults so a marker is visible without CMS setup; the full guide covers setMapOverlayMarkers for production use.
Switch between buildings — log floors as the reader enters each building on the campus map.
Large properties — airports, university campuses, retail malls — can contain more than one building. The demo subscribes to floorChange so tapping any building on the University of Guelph campus logs the building's floor list.
Deep-link to a specific map state — encode map state in a URL for direct boot.
Encode a particular map state — selected entity, active route, focused floor — in a URL so the API boots directly into that state. Powers QR-code campaigns, email links, and push notifications.
Change the map language — switch the active language to French at runtime.
The API supports multi-language properties. Entity names, category labels, floor names, and wayfinding instructions are all served in the configured language.
Set the initial map view — control the map's centre and zoom programmatically.
Control the map's centre position and zoom level programmatically. Useful for landing on a specific neighbourhood or focusing on a building entry.
The remaining guides are reference-oriented — no inline demo, but each links to runnable code in the full guide.
- Implement idle detection — kiosk soft-reset via the
idleChangeevent after a configurable timeout. - Promotions on the map — surface CMS-authored promotions via the
promotionClick+promotionDetailsevents. - Integrate with the Public API — REST entity-catalogue + the current method reference table.
- Set up a share URL — Universal-Link / App-Link configuration for the iframe's built-in share button.
- Use with React —
useMapstedMap()hook recipe (StrictMode-safe). - Use with Vue —
useMapstedMap()composable recipe. - Use with Angular — injectable
MapstedMapServicerecipe.
Explanations
Understand how the API works under the hood. Conceptual entries do not all carry inline demos — those that do are interactive below.
The event system — listen for select and tap any entity.
The API exposes a typed event system with on() / off() / once(). The demo logs each entity selection as you tap.
Feature flags explained — disable the zoom controls at runtime.
Feature flags control which UI elements are visible on the map. The demo flips zoom: false after init to hide the zoom buttons.
Boost and deep-linking — apply pre-configured map states at init or runtime.
Boosts are pre-configured map states applied at init or runtime. The full guide covers the production applyBoost + createBoostSelect / createBoostRouting pattern.
MapInstance — module vs instance API — capture the handle returned by init().
init() resolves with a MapInstance handle exposing destroy, isReady, getState, subscribe. The demo captures the handle and reads isReady().
The remaining explanations are conceptual — no inline demo:
- How it works — iframe architecture + postMessage protocol.
- Lifecycle —
UNINITIALIZED → LOADING → READY → DESTROYEDstate machine. - Versioning — release versioning policy + v2/v3 migration shim.
What next?
- Run through the tutorials for end-to-end walkthroughs.
- Browse the API reference for every public method.
- Migrating from v2 or v3? See the v3 → 26.7.1 migration guide.