Map Events

The Mapsted Maps JavaScript API emits events when the user interacts with the map or when the map state changes. Subscribe with on(name, handler) and detach with off(name, handler) or by calling the returned unsubscribe function.

Prerequisites

• A working map embed — complete Embed your first map first.
• All on() calls should be placed inside the onload callback so the API is ready to route events.

Available events

The Mapsted Maps JavaScript API defines 20 canonical events. All 20 are listed below.

Event	Fires when
mapMounted	The map iframe is mounted in the DOM
load	The map is fully loaded and ready
select	The user taps a room or POI
coordsSelect	The user taps a WGS84 coordinate (no entity)
floorChange	The active floor changes
idleChange	The map enters or exits idle state
mapOverlayMarkerSelect	The user taps a map-overlay marker
zoomLevelChange	The zoom level crosses a threshold
mapCenterChange	The map viewport center moves
promotionClick	The user clicks a promotion surface (covers the analyst-list poi_offer_clicked)
navigationStart	A route overlay is drawn (covers the analyst-list navigation_started)
searchText	The built-in search bar text changes (covers the analyst-list search_initiated and search_query_entered)
detailsView	The entity details panel opens (covers the analyst-list poi_detail_viewed)
promotionDetails	The promotion details panel opens
accessibilityChange	Accessibility routing mode is toggled
themeChange	The map theme (light/dark) switches
boostComplete	An applyBoost action has completed
all	Wildcard — fires for every event (payload includes type field)
protocolError	A protocol error occurs between the API and the iframe
buildingChange	The user navigates to a different building inside a multi-building property (payload: buildingId, previousBuildingId)

For typed payload shapes for each event, see the Events reference.

Steps

1. Listen for the select event

The select payload contains the entity that was tapped. Use it to drive a sidebar, fetch extra data, or open a custom panel.

mapsted.maps.on("select", function (payload) {
  console.log("Entity selected:", payload.entityId);
  console.log("Floor ID:", payload.floorId);
  console.log("Building ID:", payload.buildingId);
});

Open in Sandbox ↗

2. Inspect the full event payload

Log the raw payload object to discover every available field for your property.

mapsted.maps.on("select", function (payload) {
  console.log(JSON.stringify(payload, null, 2));
});

The select payload is an EntityData object with exactly buildingId, floorId, and entityId.

3. Subscribe to all events

Register a wildcard listener with on('all', fn) to deliver every API event to a single handler — useful for logging or analytics pipelines. The handler receives a single payload object with a type field identifying the event name, plus all the event-specific fields.

mapsted.maps.on('all', function (payload) {
  console.log("[mapsted]", payload.type, payload);
});

Open in Sandbox ↗

4. Read custom data attributes from an event

If you attached extra data to an entity using setEntityData, it comes back on the select event under payload.data.

mapsted.maps.setEntityData([
  {
    id: 302,    // Information 192 on property 603
    data: { department: "Information Services", capacity: 30 }
  }
]);

mapsted.maps.on("select", function (payload) {
  if (payload.data && payload.data.department) {
    console.log(payload.data.department + " — capacity: " + payload.data.capacity);
  }
});

5. Listen for a single event (fire once)

Use the built-in once() helper to subscribe to an event that fires at most once. It returns an unsubscribe function and automatically detaches the handler after the first invocation.

mapsted.maps.once("select", function (payload) {
  console.log("You selected entity:", payload.entityId);
});

6. Remove a listener

Always remove listeners when the map is destroyed or when your component unmounts (React, Vue, etc.) to prevent memory leaks. Pass the same function reference you gave to on(), or call the unsubscribe function returned by on().

function handleSelect(payload) {
  console.log("selected", payload.entityId);
}

// attach — returns an unsubscribe function
const unsub = mapsted.maps.on("select", handleSelect);

// detach via returned function
unsub();

// OR detach via off() with the original reference
mapsted.maps.off("select", handleSelect);

V2/V3 event API deprecated

mapsted.maps.addEventListener() and mapsted.maps.removeEventListener() are deprecated V2/V3 compatibility shims. They emit a console.warn and throw MAPSTED-1093 in strict mode. Migrate to the emitter API:

V2/V3 shim	Canonical
addEventListener(name, fn)	on(name, fn)
removeEventListener(name, fn)	off(name, fn)
(manual once pattern)	once(name, fn)

The on() handler receives the unwrapped payload directly (not a CustomEvent), so remove any event.detail access — use payload.entityId instead of event.detail.entityId.

Expected output

Opening the browser console and tapping a room in the University of Windsor demo (property 603) prints a JSON object containing the entity ID, floor ID, and building ID. The wildcard 'all' handler prints one line per interaction.

Next steps

• Use the floorChange event while navigating: Floor navigation
• Attach custom data to entities: Markers and popups