Events

Event callbacks are the main way to keep your host application in sync with map state.

Subscribe with on and unsubscribe with off:

map.on(eventName, handler);
map.off(eventName, handler);

---

Event summary

Event	Payload	When it fires
ready	void	After map initialization completes
viewchange	ViewState	When map movement settles
layerchange	Layer[]	After layer updates (API or built-in UI)
basemapchange	"basemap" | "satellite" | "hybrid" | "basemap-2.5d" | "hybrid-2.5d"	After basemap switches

---

ready

Use this as your integration checkpoint.
Attach the callback immediately after construction and place map-dependent setup inside it.

map.on("ready", () => {
  console.log("Map is interactive");
});

---

viewchange

This event provides normalized view state:

type ViewState = {
  center: [number, number];
  bearing: number;
  zoom: number;
};

Example:

map.on("viewchange", (view) => {
  // push into external state, analytics, or 3D sync layer
  console.log(view.center, view.zoom, view.bearing);
});

---

layerchange

Fires after any layer mutation, including:

• visibility toggles
• opacity changes
• order changes
• layer add/remove actions

map.on("layerchange", (layers) => {
  // update host-side layer UI
  console.log("Current layers:", layers);
});

---

basemapchange

Use this to keep host UI controls in sync.

map.on("basemapchange", (basemap) => {
  console.log("Active basemap:", basemap);
});

---

Recommended pattern

Define stable named handlers when you need clean teardown:

function handleViewChange(view: { center: [number, number]; bearing: number; zoom: number }) {
  // ...
}

map.on("viewchange", handleViewChange);
// later
map.off("viewchange", handleViewChange);