Event Listeners

As there are different kind of events that you might be interested in, the viewer has an event system to listen to them. The event listener is called whenever this event is emitted. The event listener is added with a callback and can be removed with the token that has been received.

In the following example, we register an event listener whenever the scene has been customized.

TYPESCRIPT

// create a listener that is called whenever the session has been customized
const token = addListener(EVENTTYPE.SESSION.SESSION_CUSTOMIZED, (e) => {
  console.log("Session customized", `Session customized: ${JSON.stringify(e)}`);
});

session.getParameterByName("Length")[0].value = 10;
await session.customize();

// once you are done listening, remove the listener
// removeListener(token)

Available Event Types

The viewer provides several categories of events through the EVENTTYPE object. Below is a summary of the most commonly used events in each category.

Session Events (`EVENTTYPE.SESSION`)

Event	Fires when
`SESSION_CREATED`	A new session has been created.
`SESSION_CUSTOMIZED`	A customization request completes and the scene is updated with new outputs.
`SESSION_INITIAL_OUTPUTS_LOADED`	The initial outputs of a session have been loaded and are ready.
`SESSION_CLOSED`	A session has been closed.
`SESSION_ERROR`	An error occurred in the session.

Viewport Events (`EVENTTYPE.VIEWPORT`)

Event	Fires when
`VIEWPORT_CREATED`	A new viewport has been created.
`VIEWPORT_UPDATED`	The viewport has been updated.
`BUSY_MODE_ON`	The viewport busy mode has started (a session is computing).
`BUSY_MODE_OFF`	The viewport busy mode has ended.

Camera Events (`EVENTTYPE.CAMERA`)

Event	Fires when
`CAMERA_START`	The user begins interacting with the camera (orbit, pan, zoom).
`CAMERA_END`	The user stops interacting with the camera.
`CAMERA_MOVE`	The camera position or target changes (fires continuously during interaction).

Interaction Events (`EVENTTYPE.INTERACTION`)

Event	Fires when
`SELECT_ON`	An object has been selected.
`SELECT_OFF`	An object has been deselected.
`HOVER_ON`	The mouse hovers over an interactive object.
`HOVER_OFF`	The mouse leaves an interactive object.
`DRAG_START`	A drag interaction begins.
`DRAG_MOVE`	A dragged object moves.
`DRAG_END`	A drag interaction ends.

Scene Events (`EVENTTYPE.SCENE`)

Event	Fires when
`SCENE_BOUNDING_BOX_CHANGE`	The bounding box of the scene has changed.
`SCENE_BOUNDING_BOX_EMPTY`	The bounding box of the scene is empty.

Output Events (`EVENTTYPE.OUTPUT`)

Event	Fires when
`OUTPUT_UPDATED`	An output has been updated with new content after a customization.

Task Events (`EVENTTYPE.TASK`)

Event	Fires when
`TASK_START`	A task (e.g., customization request) has started.
`TASK_PROCESS`	A task progress has been updated.
`TASK_END`	A task has ended.
`TASK_CANCEL`	A task has been cancelled.

Parameter Events (`EVENTTYPE.PARAMETER`)

Event	Fires when
`PARAMETER_VALUE_CHANGED`	A parameter's value has changed (locally, before customize).
`PARAMETER_SESSION_VALUE_CHANGED`	A parameter's session value has changed (after a successful customization).

For the complete list of events and their payload types, see the EVENTTYPE reference in the API documentation.

Listening to Multiple Events

You can register listeners for multiple event types. Each listener returns a token that you can use to remove it later:

TYPESCRIPT

// Listen for camera changes
const cameraToken = addListener(EVENTTYPE.CAMERA.CAMERA_END, (e) => {
  console.log("Camera stopped moving", e);
});

// Listen for selection events
const selectToken = addListener(EVENTTYPE.INTERACTION.SELECT_ON, (e) => {
  console.log("Selection changed", e);
});

// Clean up when done
removeListener(cameraToken);
removeListener(selectToken);

Always remove listeners when they are no longer needed, especially in frameworks like React where components unmount and remount. See the Troubleshooting page for guidance on avoiding stale closures in React event handlers.

Available Event Types

Session Events (EVENTTYPE.SESSION)

Viewport Events (EVENTTYPE.VIEWPORT)

Camera Events (EVENTTYPE.CAMERA)

Interaction Events (EVENTTYPE.INTERACTION)

Scene Events (EVENTTYPE.SCENE)

Output Events (EVENTTYPE.OUTPUT)

Task Events (EVENTTYPE.TASK)

Parameter Events (EVENTTYPE.PARAMETER)