ThreeView Events

This page describes all events available on a ThreeView instance.

Methods

on()

Registers event listeners for various view events.

on<K extends keyof ViewEvents>(event: K, handler: ViewEvents[K]): void

off()

Removes an event listener.

off<K extends keyof ViewEvents>(event: K, handler: ViewEvents[K]): void

Example:

const resizeHandler = (width, height) => {
  console.log(`Resized to ${width}x${height}`);
};

// Register event listener
view.on("resize", resizeHandler);

// Later, remove the listener
view.off("resize", resizeHandler);

Advanced Example

// Create named handlers for easy cleanup
const handlers = {
  handleClick: (event) => {
    console.log("Clicked:", event);
  },
  handleResize: (width, height) => {
    console.log(`Resized: ${width}x${height}`);
  },
  handlePick: (info) => {
    if (info) {
      console.log("Picked:", info.properties);
    }
  },
};

// Register multiple listeners
view.on("click", handlers.handleClick);
view.on("resize", handlers.handleResize);
view.on("featureClick", handlers.handlePick);

// Later, cleanup all listeners
view.off("click", handlers.handleClick);
view.off("resize", handlers.handleResize);
view.off("featureClick", handlers.handlePick);

Event Types

resize

Description:

Fires when the window is resized. Receives width and height in pixels.

Handler Type:

(width: number, height: number) => void

Parameters:

width: Width after resize (pixels)
height: Height after resize (pixels)

Example:

view.on("resize", (width, height) => {
  console.log(`Window resized: ${width}x${height}`);
});

featureClick

Description:

Fires when a feature is clicked or tapped. Receives the clicked feature information, or null if empty space was clicked. For raw click coordinates, use the click event instead.

The click pick is lazy: the GPU pick runs only while at least one featureClick listener is registered.

Handler Type:

(info: PickedFeature | null) => void

Parameters:

info: Clicked feature information, or null

type PickedFeature = {
  batchId: number; // Batch ID
  properties: Record<string, unknown> | undefined; // Feature properties
  layerId: string | undefined; // Layer ID
};

Example:

view.on("featureClick", (info) => {
  if (info) {
    console.log("Selected feature:", info.properties);
    console.log("Layer ID:", info.layerId);
    console.log("Batch ID:", info.batchId);
  } else {
    console.log("No feature selected");
  }
});

featureHover

Description:

Fires when the hovered feature changes as the pointer moves. Receives the newly hovered feature, or null when the pointer leaves all pickable features. The event fires only on change, not on every pointer move.

Hover picking runs a GPU pick per frame while the pointer moves, so it is activated lazily: picks run only while at least one featureHover, featureEnter, or featureLeave listener is registered, and are suppressed while a button or finger is pressed (for example, during a camera drag). Because touch contact always counts as pressed, hover events never fire for touch.

Handler Type:

(info: PickedFeature | null) => void

Parameters:

info: Hovered feature information, or null

Example:

view.on("featureHover", (info) => {
  view.canvas.style.cursor = info ? "pointer" : "";
});

featureEnter

Description:

Fires when the pointer starts hovering a pickable feature. Together with featureLeave, this is synthesized from the same hover picking as featureHover, so the same activation rules apply.

Handler Type:

(info: PickedFeature) => void

Parameters:

info: The feature the pointer started hovering

Example:

view.on("featureEnter", (info) => {
  console.log("Entered feature:", info.properties);
});

featureLeave

Description:

Fires when the pointer stops hovering the previously hovered feature. Receives the feature that was left. When the pointer moves directly from one feature to another, featureLeave fires for the previous feature before featureEnter fires for the new one.

Handler Type:

(info: PickedFeature) => void

Parameters:

info: The feature the pointer stopped hovering

Example:

view.on("featureLeave", (info) => {
  console.log("Left feature:", info.properties);
});

layer

Description:

Fires when a layer-related event occurs.

Handler Type:

<K extends keyof LayerEvent>(
  k: K,
  layerId: string,
  ...args: Parameters<LayerEvent[K]>
) => void

Example:

view.on("layer", (eventType, layerId, ...args) => {
  console.log(`Layer ${layerId} event: ${eventType}`, args);
});

preUpdate

Description:

Fires before the update process. Receives a DOMHighResTimeStamp as a timestamp.

Handler Type:

(time: number) => void

Parameters:

time: DOMHighResTimeStamp (high-precision timestamp in milliseconds)

Example:

view.on("preUpdate", (time) => {
  // Custom logic before update
  console.log(`Before update: ${time}ms`);
});

postUpdate

Description:

Fires after the update process when state changes have occurred. Receives a DOMHighResTimeStamp as a timestamp.

Handler Type:

(time: number) => void

Parameters:

time: DOMHighResTimeStamp (high-precision timestamp in milliseconds)

Example:

view.on("postUpdate", (time) => {
  // Custom logic after update
  console.log(`After update: ${time}ms`);
});

preRender

Description:

Fires before rendering. When animation: true, fires every frame. Receives a DOMHighResTimeStamp as a timestamp.

Handler Type:

(time: number) => void

Parameters:

time: DOMHighResTimeStamp (high-precision timestamp in milliseconds)

Example:

view.on("preRender", (time) => {
  // Custom logic before rendering
  console.log(`Before render: ${time}ms`);
});

postRender

Description:

Fires after rendering. When animation: true, fires every frame. Receives a DOMHighResTimeStamp as a timestamp.

Handler Type:

(time: number) => void

Parameters:

time: DOMHighResTimeStamp (high-precision timestamp in milliseconds)

Example:

view.on("postRender", (time) => {
  // Custom logic after rendering
  console.log(`After render: ${time}ms`);
});

pointerdown

Description:

Fires when a pointer (mouse button, touch, or pen) is pressed on the map. Receives a MapPointerEvent containing map coordinates. Use event.pointerType ("mouse", "touch", or "pen") to tell the input kinds apart.

Handler Type:

(event: MapPointerEvent) => void

Parameters:

event: Pointer event (containing map coordinates)

type MapPointerEvent = {
  map: { x: number; y: number; z: number }; // ECEF coordinates on the globe surface
} & PointerEvent;

Example:

view.on("pointerdown", (event) => {
  console.log(`Pointer down position: ${event.clientX}, ${event.clientY}`);
  console.log(
    `Map coordinates (ECEF): ${event.map.x}, ${event.map.y}, ${event.map.z}`
  );
});

pointerenter

Description:

Fires when a pointer enters the canvas area. Receives a MapPointerEvent containing map coordinates.

Handler Type:

(event: MapPointerEvent) => void

Parameters:

event: Pointer event (containing map coordinates)

Example:

view.on("pointerenter", (event) => {
  console.log("Pointer entered the map");
  console.log(`Map coordinates: ${event.map.x}, ${event.map.y}, ${event.map.z}`);
});

pointerleave

Description:

Fires when a pointer leaves the canvas area. Receives a MapPointerEvent containing map coordinates. For touch, this fires after the finger is lifted.

Handler Type:

(event: MapPointerEvent) => void

Parameters:

event: Pointer event (containing map coordinates)

Example:

view.on("pointerleave", (event) => {
  console.log("Pointer left the map");
});

pointermove

Description:

Fires when a pointer moves on the map. Receives a MapPointerEvent containing map coordinates. For touch, this fires while a finger drags across the map.

Handler Type:

(event: MapPointerEvent) => void

Parameters:

event: Pointer event (containing map coordinates)

Example:

view.on("pointermove", (event) => {
  console.log(`Pointer position: ${event.clientX}, ${event.clientY}`);
  console.log(
    `Map coordinates (ECEF): ${event.map.x}, ${event.map.y}, ${event.map.z}`
  );
});

pointerup

Description:

Fires when a pointer (mouse button, touch, or pen) is released on the map. Receives a MapPointerEvent containing map coordinates.

Handler Type:

(event: MapPointerEvent) => void

Parameters:

event: Pointer event (containing map coordinates)

Example:

view.on("pointerup", (event) => {
  console.log(`Pointer up position: ${event.clientX}, ${event.clientY}`);
  console.log(`Map coordinates: ${event.map.x}, ${event.map.y}, ${event.map.z}`);
});

pointercancel

Description:

Fires when the browser cancels an active pointer, for example when a system gesture takes over a touch. Receives the raw PointerEvent without map coordinates.

Handler Type:

(event: PointerEvent) => void

Example:

view.on("pointercancel", () => {
  console.log("Pointer interaction cancelled");
});

idle

Description:

Fires when data and tile processing becomes idle, that is, when no updates such as tile loading or data processing have occurred for at least idleThreshold milliseconds. Continuous animations and effects do not count as activity, so this event fires even while they are running. It fires at most once per idle period and resets when processing activity resumes.

Handler Type:

() => void

Example:

view.on("idle", () => {
  console.log("Data and tile processing is idle");
});

click

Description:

Fires when the map is clicked or tapped. Receives a MapPointerEvent containing map coordinates; event.pointerType tells the input kinds apart.

Handler Type:

(event: MapPointerEvent) => void

Parameters:

event: Pointer event (containing map coordinates)

Example:

view.on("click", (event) => {
  console.log(`Click position: ${event.clientX}, ${event.clientY}`);
  console.log(`Input type: ${event.pointerType}`);
  console.log(
    `Map coordinates (ECEF): ${event.map.x}, ${event.map.y}, ${event.map.z}`
  );
});