Reading state

Events describe changes. getState() describes the present, which is what you want when your page needs to know where things stand rather than what just happened.

Examples use a demonstration campus. Every snippet on this site addresses ucba, a publicly available campus with the building muntz-hall and the room 170. Substitute your own campus slug once you have one. Slugs for your campus are listed in your Waylocate console, and the addressing rules are in the reference grammar.

Taking a snapshot

const state = await map.getState();

interface MapState {
  ready: boolean;
  campus: string;
  building: string | null;
  floor: string | null;
  room: string | null;
  directions: {
    from: string | null;
    to: string | null;
    mode: "preview" | "live";
  } | null;
  camera: CameraPosition | null;
  url: string;
}

Field	Notes
ready	false until the campus data has finished loading
building	Building slug, or null when nothing is selected
floor	Floor slug, relative to the building
room	Room reference, bare and relative to the building
directions	null when no route is drawn
camera	null while the map is not rendering
url	Canonical full-map URL for the current state

Fields that cannot be expressed as a reference degrade to null rather than failing. A route endpoint the visitor tapped on the map has no reference, and a building with no slug encodes as null even while it is selected.

The url field

url is the shareable, full-map address for whatever the map is currently showing. It is included so that you can build your own share button, deep link, or open-in-new-tab control without reconstructing the URL grammar yourself.

async function share() {
  const { url } = await map.getState();
  await navigator.clipboard.writeText(url);
}

Following state

state.changed carries the same snapshot and fires on any change. It is the catch-all: use it when you want to mirror the map's state rather than respond to specific transitions.

map.on("state.changed", (state) => {
  syncStore(state);
});

For anything narrower, the specific events are cheaper and clearer. selection.changed and directions.changed carry only what changed, and are documented in events.

The camera is not part of change detection

camera is read from the map each time you call getState() rather than being cached, and camera movement does not raise state.changed. If it did, every pan gesture would count as a state change and a host mirroring state would re-render continuously.

To follow the camera, subscribe to camera.idle, which fires once after motion settles. See camera.

Next

• Events for the full catalogue.
• Errors for failure handling.