Events reference

Every listener on the Felt controller follows the same pattern: you pass a handler (and sometimes an options object scoping the listener to a specific entity), and the call returns an unsubscribe function.

const unsubscribe = felt.onLayerChange({
  options: { id: "layer-1" },
  handler: ({ layer }) => console.log(layer.bounds),
});

// ...later, when you no longer need the listener
unsubscribe();

Always call the unsubscribe function when your UI unmounts or the listener is no longer needed.

Viewport and map state

Listener	Scoping options	Handler receives
onViewportMove	—	ViewportState — fires continuously during movement, including during animations and inertia.
onViewportMoveEnd	—	ViewportState — fires once when dragging, zooming, animations, and inertia have finished.
onMapIdle	—	Nothing. Fires when the map is fully idle: no transitions, no interaction, all tiles loaded, fades complete.
onBasemapChange	—	Basemap — the new basemap.

Annotations (elements)

Listener	Scoping options	Handler receives
onElementCreate	—	{ element: Element | null, isBeingCreated: boolean } — fires repeatedly while the user draws (isBeingCreated: true), then a final time with isBeingCreated: false.
onElementCreateEnd	—	{ element: Element } — fires once, when creation is finished.
onElementChange	{ id }	{ element: Element | null, isBeingCreated: boolean } — element is null if it was removed.
onElementDelete	{ id }	Nothing.
onElementGroupChange	{ id }	{ elementGroup: ElementGroup | null }

Layers and legends

Listener	Scoping options	Handler receives
onLayerChange	{ id }	{ layer: Layer | null }
onLayerGroupChange	{ id }	{ layerGroup: LayerGroup | null }
onLegendItemChange	{ id, layerId }	{ legendItem: LegendItem | null }
onLayerFiltersChange	{ layerId }	LayerFilters — the bare filters object ({ style, components, ephemeral, combined }), with no wrapper. See Layer filters.
onLayerBoundariesChange	{ layerId }	LayerBoundaries | null

Pointer and selection

Listener	Scoping options	Handler receives
onPointerClick	—	MapInteractionEvent — { coordinate, point, features, rasterValues }. features and rasterValues are arrays (empty when nothing is under the pointer).
onPointerMove	—	MapInteractionEvent
onSelectionChange	—	{ selection: EntityNode[] } — see Working with selection.

Tools

Listener	Scoping options	Handler receives
onToolChange	—	ToolType | null — the newly selected tool, or null when no tool is active.
onToolSettingsChange	—	ToolSettingsChangeEvent — a discriminated union: check the tool field to narrow to that tool's settings.

For payload type details, follow each method's entry in the API reference.