Appearance

The Event System ​

The Mapsted Maps JavaScript API exposes a typed event system with on() / off() / once() methods.

Open in Sandbox ↗

Two Categories of Events ​

  1. Canonical known events (20): Typed payloads, IDE autocomplete via KnownEventName — see the Map Events tutorial for the full list.
  2. Customer-defined events: Via HTML data-mapsted-event attributes, unknown payload.

Note: data-mapsted-* attributes are an internal escape-hatch of the Mapsted Maps web iframe, not part of the public JS API surface, and may change without a major-version bump.

Subscribing to Events ​

javascript
// Known event — typed payload
mapsted.maps.on('select', (entity) => {
  console.log(entity.entityId); // TypeScript knows this is EntityData
});

// Escape-hatch — unknown payload
mapsted.maps.on('my-custom-event', (payload) => {
  console.log(payload); // Type: unknown
});

Unsubscribing ​

javascript
// Option 1: Use the returned unsubscribe function
const unsub = mapsted.maps.on('select', handler);
unsub(); // Removes the listener

// Option 2: Use off()
mapsted.maps.off('select', handler);

Fire-once pattern ​

Use the built-in once() helper — it subscribes, fires the handler the first time the event occurs, then auto-unsubscribes:

javascript
mapsted.maps.once('load', () => {
  console.log('Map loaded — this fires only once');
});

once() returns the same Unsubscribe function as on(), so you can also cancel before the event fires:

javascript
const cancel = mapsted.maps.once('load', () => { /* … */ });
cancel(); // Cancels the one-shot subscription if not yet fired

Wildcard ​

javascript
mapsted.maps.on('all', ({ type, ...payload }) => {
  console.log(`Event: ${type}`, payload);
});

V2/V3 migration note ​

V2/V3 used addEventListener / removeEventListener. Both still work via a deprecation shim that emits a console.warn on first call. Migrate to on / off / once before the shim is removed in the next major release.

See also: Events Reference | Map Events Tutorial