Events
NiiVue uses the standard EventTarget API. Every controller instance is an EventTarget, so you use addEventListener and removeEventListener just like a DOM element.
All events are fully typed via NVEventMap. TypeScript will infer the correct CustomEvent<T> detail type for each event name when using addEventListener/removeEventListener.
Quick Start
import NiiVue from '@niivue/niivue'
const nv = new NiiVue({ backgroundColor: [0, 0, 0, 1] })await nv.attachToCanvas(document.getElementById('gl'))
// Listen for crosshair navigationnv.addEventListener('locationChange', (e) => { console.log(e.detail.string) // human-readable location console.log(e.detail.mm) // [x, y, z] in mm console.log(e.detail.values) // per-volume intensity values})
// Listen for any property changenv.addEventListener('change', (e) => { console.log(`${e.detail.property} = ${e.detail.value}`)})
// Clean upconst handler = (e) => { /* ... */ }nv.addEventListener('volumeLoaded', handler)nv.removeEventListener('volumeLoaded', handler)TypeScript Usage
Event listeners are fully typed. The detail type is inferred from the event name:
import NiiVue from '@niivue/niivue'
const nv = new NiiVue()
nv.addEventListener('locationChange', (evt) => { // evt is CustomEvent<NiiVueLocation> — fully typed const { mm, vox, values } = evt.detail})
nv.addEventListener('documentLoaded', (evt) => { // evt is Event (no detail) — events with undefined payload use plain Event})Emission timing
Events are emitted so that the item an event references is present in the
collection (nv.volumes / nv.meshes) at the moment the event fires:
- Add / update / reorder fire after the model changes — the item is now
present or updated (
volumeLoaded,meshLoaded,volumeUpdated,meshUpdated,volumeOrderChanged). - Removal also fires after the model changes — the item is gone from the
collection, and the event
detailcarries it together with its former index (volumeRemoved,meshRemoved,signalRemoved,measurementRemoved, and the bulk forms, which emit once per item in reverse index order).
Consumer corollary: a listener may re-read the collection synchronously
inside any of these events and see the post-mutation state. To inspect a
departing item, use detail. New emitting methods should preserve this
ordering: emit after the mutation.
Event Reference
User Interaction
locationChange
Fired when the crosshair position changes (user click, keyboard navigation, or programmatic), and on a slide plane when a landing tile changes the slide samples under the crosshair.
| Field | Type | Description |
|---|---|---|
mm |
[number, number, number] |
Position in mm |
vox |
[number, number, number] |
Rounded voxel indices |
frac |
[number, number, number] |
Scene fraction [0..1] |
xy |
[number, number] |
Mouse position on canvas |
axCorSag |
number |
Slice orientation (0=sagittal, 1=coronal, 2=axial); SLICE_TYPE.RENDER for a 3D render depth pick |
values |
NiiVueLocationValue[] |
Per-volume data (name, value, label) |
slide |
NiiVueLocationSlide? |
On a slide plane, when the crosshair projected onto it is on the slide: {id, name, x, y, samples}, base-level pixel and one NVSlideSample per channel from the tile cache (value null when missing). Re-emitted when a landing tile changes the samples |
string |
string |
Human-readable location with values |
nv.addEventListener('locationChange', (e) => { document.getElementById('info').textContent = e.detail.string})frameChange
Fired when the current 4D frame changes on a volume. For a volume with a
frameSource (frames fetched on demand) it fires once the new frame is in
img, for each volume of the source’s group.
| Field | Type | Description |
|---|---|---|
volume |
NVImage |
The volume whose frame changed |
frame |
number |
New frame index (0-based) |
nv.addEventListener('frameChange', (e) => { slider.value = e.detail.frame})dragRelease
Fired when any drag interaction completes on a 2D slice.
| Field | Type | Description |
|---|---|---|
tileIdx |
number |
Index of the tile where drag occurred |
axCorSag |
number |
Slice orientation |
mmLength |
number |
Drag distance in mm |
voxStart |
[number, number, number] |
Start position (voxel, rounded) |
voxEnd |
[number, number, number] |
End position (voxel, rounded) |
mmStart |
[number, number, number] |
Start position in mm |
mmEnd |
[number, number, number] |
End position in mm |
measurementCompleted
Fired when a distance measurement line is completed — by an interactive drag in
DRAG_MODE.measurement or by a programmatic addMeasurement call. Fired after
the measurement is appended, so it is already in getMeasurements(). A click (zero length) adds nothing.
| Field | Type | Description |
|---|---|---|
startMM |
[number, number, number] |
Start point in mm |
endMM |
[number, number, number] |
End point in mm |
distance |
number |
Distance in mm |
sliceIndex |
number |
Slice tile index |
sliceType |
number |
Slice orientation |
slicePosition |
number |
Slice position as a scene fraction (recorded from scene.crosshairPos), not mm |
measurementRemoved
Fired by removeMeasurement after the measurement is removed; detail
carries the removed measurement and its former index.
| Field | Type | Description |
|---|---|---|
measurement |
CompletedMeasurement |
The measurement being removed |
index |
number |
Its index in the measurement list |
angleCompleted
Fired when an angle measurement (two lines) is completed.
| Field | Type | Description |
|---|---|---|
firstLine |
{ startMM, endMM } |
First line endpoints in mm |
secondLine |
{ startMM, endMM } |
Second line endpoints in mm |
angle |
number |
Angle in degrees |
sliceIndex |
number |
Slice tile index |
sliceType |
number |
Slice orientation |
slicePosition |
number |
Slice position as a scene fraction (recorded from scene.crosshairPos), not mm |
pointerUp
Fired on every pointer release over the canvas.
| Field | Type | Description |
|---|---|---|
x |
number |
Pointer X offset on canvas |
y |
number |
Pointer Y offset on canvas |
button |
number |
Mouse button (0=left, 1=middle, 2=right) |
Loading & Removal
volumeLoaded
Fired after a volume is successfully added (via addVolume() or loadVolumes()). Fires once per volume.
| Field | Type | Description |
|---|---|---|
volume |
NVImage |
The newly loaded volume |
meshLoaded
Fired after a mesh is successfully added (via addMesh() or loadMeshes()). Fires once per mesh added; a mesh the model cannot read is logged and fires nothing. detail.mesh is the added mesh, not the last entry of nv.meshes.
| Field | Type | Description |
|---|---|---|
mesh |
NVMesh |
The newly loaded mesh |
volumeRemoved
Fired after a volume is removed — by removeVolume(index), or once per volume in reverse order by removeAllVolumes(). The volume is no longer in nv.volumes; detail carries it and its former index.
| Field | Type | Description |
|---|---|---|
volume |
NVImage |
The volume being removed |
index |
number |
Index in the volumes array |
meshRemoved
Fired after a mesh is removed — by removeMesh(index), or once per mesh in reverse order by removeAllMeshes(). The mesh is no longer in nv.meshes; detail carries it and its former index.
| Field | Type | Description |
|---|---|---|
mesh |
NVMesh |
The mesh being removed |
index |
number |
Index in the meshes array |
documentLoaded
Fired after loadDocument() completes. No detail payload — the loaded state is reflected in the model. By then any half-drawn annotation, the annotation selection, and the annotationUndo() history from the previous scene have been cleared.
nv.addEventListener('documentLoaded', () => { console.log(`Loaded ${nv.volumes.length} volumes`)})View Lifecycle
viewAttached
Fired after attachToCanvas() or attachTo() completes successfully (GPU initialized, interaction handlers set up).
| Field | Type | Description |
|---|---|---|
canvas |
HTMLCanvasElement |
The attached canvas |
backend |
'webgpu' | 'webgl2' |
Active rendering backend |
nv.addEventListener('viewAttached', (e) => { console.log(`Rendering with ${e.detail.backend}`)})viewDestroyed
Fired when destroy() is called, before teardown begins. No detail payload.
canvasResize
Fired when the canvas is resized (via ResizeObserver).
| Field | Type | Description |
|---|---|---|
width |
number |
New canvas clientWidth |
height |
number |
New canvas clientHeight |
nv.addEventListener('canvasResize', (e) => { overlay.style.width = `${e.detail.width}px`})View Control
azimuthElevationChange
Fired when azimuth or elevation is set programmatically, or when the user
rotates the 3D render view (mouse drag or the H/J/K/L keys).
| Field | Type | Description |
|---|---|---|
azimuth |
number |
Current azimuth (degrees) |
elevation |
number |
Current elevation (degrees) |
clipPlaneChange
Fired when a clip plane is modified via setClipPlane() or setClipPlaneDepthAziElev().
| Field | Type | Description |
|---|---|---|
clipPlane |
number[] |
[depth, azimuth, elevation] |
sliceTypeChange
Fired when sliceType is set.
| Field | Type | Description |
|---|---|---|
sliceType |
number |
New slice type value |
Data Updates
volumeUpdated
Fired after setVolume() applies property changes to a volume, including a
colormap change between a continuous and a label colormap.
Not fired by updateVolumeData(), which edits voxel values (typically every
frame) without changing any display option.
| Field | Type | Description |
|---|---|---|
volumeIndex |
number |
Index of the updated volume |
volume |
NVImage |
The volume (after update) |
changes |
VolumeUpdate |
The options that were applied; calMin/calMax, when present, are the resolved window (a NaN request reports the image default, a CT map’s fill its window) |
nv.addEventListener('volumeUpdated', (e) => { const { volumeIndex, changes } = e.detail if (changes.colormap) updateColormapUI(volumeIndex, changes.colormap)})meshUpdated
Fired after setMesh() applies property changes to a mesh, or after a
scalar-overlay layer change (addMeshLayer, removeMeshLayer,
setMeshLayerProperty). Not fired by updateMeshPositions(), which moves
vertices (typically every frame) without changing any display option.
| Field | Type | Description |
|---|---|---|
meshIndex |
number |
Index of the updated mesh |
mesh |
NVMesh |
The mesh (after update) |
changes |
MeshUpdate |
The options that were applied — empty ({}) for layer changes, since layer state isn’t a MeshUpdate diff; re-read mesh.layers |
colormapAdded
Fired after addColormap() or addColormapFromUrl() registers a new user-defined colormap. The new LUT is then visible to volumes, mesh layers, colorbars, connectomes, and tracts.
| Field | Type | Description |
|---|---|---|
name |
string |
Registered colormap name |
nv.addEventListener('colormapAdded', (e) => { populateColormapDropdown(nv.colormaps) console.log(`registered ${e.detail.name}`)})Chunk Streaming
Chunked (oversized) volumes stream their bricks to the GPU over multiple
frames. These events replace polling chunkStreamStats() on a timer. Both
carry a ChunkStreamDetail — the same shape as the non-null return of
chunkStreamStats(), and the method reads back the same counts at emit time.
| Field | Type | Description |
|---|---|---|
resident |
number |
Bricks currently GPU-resident |
pending |
number |
Bricks queued for upload |
inFlight |
number |
Bricks mid-upload |
total |
number |
Bricks in the plan |
staleDropped |
number |
Cumulative queued uploads retired because the view moved on |
predicted |
number |
Cumulative speculative source reads |
retiring |
number |
Replaced bricks a keepUntilCovered swap still draws |
retiringBytes |
number |
GPU bytes those bricks hold |
decoded |
ByteLruStats |
Decoded-chunk (CPU byte) tier counters |
chunkStreamProgress
Fired on a drawn frame while streaming is outstanding (pending + inFlight > 0),
whenever a count changed since the last emission — identical back-to-back
snapshots are skipped, so the render loop’s cadence bounds the rate (no timer).
The final, settled counts are also emitted as progress, immediately before
chunkStreamIdle.
chunkStreamIdle
Fired when the stream settles: a drawn frame had pending + inFlight > 0, and a
later drawn frame is complete — nothing queued or mid-upload for the working set
that frame requested, and no brick still cross-fading in. It is emitted after
that frame’s draw has been submitted, so the canvas shows every brick the frame
asked for and a listener may capture it.
What idle does and does not promise:
resident < totalon the idle frame is normal under a residency budget: idle means the visible working set is resident, not the whole plan.- A brick whose upload failed is not resident and does not settle the stream; the next drawn frame re-requests it.
- Because
chunkStreamStats()returns zeroed counts (not null) whenever a view is attached, idle is defined on this transition — it never fires for a view that is attached but has not streamed. - Streaming that resumes (e.g. a camera move queues new bricks) re-arms it, so it fires once per settle.
nv.addEventListener('chunkStreamProgress', (e) => { spinner.textContent = `${e.detail.resident} / ${e.detail.total} bricks`})nv.addEventListener('chunkStreamIdle', () => { spinner.hidden = true // the frame on screen shows every brick it asked for})Drawing
drawingChanged
Fired on drawing lifecycle events and user strokes.
| Field | Type | Description |
|---|---|---|
action |
'stroke' | 'create' | 'close' | 'undo' | 'load' | 'update' |
What happened |
'create'—createEmptyDrawing()was called'stroke'— user completed a pen stroke (pointerup)'undo'—drawUndo()restored a previous state'close'—closeDrawing()destroyed the drawing'load'—loadDrawing()loaded a drawing from a volume'update'— the drawing bitmap was updated programmatically (extensionctx.drawing.update())
drawingEnabled
Fired when drawIsEnabled is set.
| Field | Type | Description |
|---|---|---|
isEnabled |
boolean |
Whether drawing mode is now active |
penValueChanged
Fired when drawPenValue is set.
| Field | Type | Description |
|---|---|---|
penValue |
number |
New pen label index |
Annotations
annotationAdded
Fired when a new vector annotation is added.
| Field | Type | Description |
|---|---|---|
annotation |
VectorAnnotation |
The newly added annotation |
annotationRemoved
Fired when a vector annotation is removed.
| Field | Type | Description |
|---|---|---|
id |
string |
ID of the removed annotation |
annotationChanged
Fired on annotation editing events (draw, erase, move, resize, undo, redo, clear).
A draw fires annotationAdded and then annotationChanged with the new id in added; annotations it merged or cut appear in updated or removed. addAnnotation and removeAnnotation fire only annotationAdded / annotationRemoved; loadAnnotationsJSON and loadDocument fire neither.
| Field | Type | Description |
|---|---|---|
action |
'draw' | 'erase' | 'move' | 'resize' | 'undo' | 'redo' | 'clear' |
What happened |
added |
string[] |
Ids of annotations the change added |
updated |
string[] |
Ids of annotations whose geometry, stats or text changed |
removed |
string[] |
Ids of annotations the change removed |
Ids are VectorAnnotation.id, which must be unique (drawn annotations get a random UUID).
Generic Property Change
change
Fired by every property setter on the controller. Use this for unified state tracking without subscribing to individual events.
| Field | Type | Description |
|---|---|---|
property |
string |
Property name (matches the setter name, e.g. 'azimuth', 'isColorbarVisible') |
value |
unknown |
New value |
// Log all property changesnv.addEventListener('change', (e) => { console.log(`${e.detail.property} changed to`, e.detail.value)})
// React to specific propertiesnv.addEventListener('change', (e) => { if (e.detail.property === 'backgroundColor') { document.body.style.background = `rgba(${e.detail.value})` }})Properties that emit change include all controller setters: azimuth, elevation, crosshairPos, sliceType, backgroundColor, isColorbarVisible, volumeIllumination, meshXRay, drawPenValue, primaryDragMode, and all others. Some setters also emit a more specific event (e.g. azimuthElevationChange, sliceTypeChange). Setting annotationTool to its current value is a no-op: it emits no change and keeps the selection and any half-drawn shape.
Migrating from Callbacks
The old callback-based API (onLocationChange, onFrameChange, onDragRelease) has been replaced by events. Migration is straightforward:
// Before (callbacks in constructor)const nv = new NiiVue({ onLocationChange: (data) => { /* ... */ }, onFrameChange: (volume, frame) => { /* ... */ }, onDragRelease: (info) => { /* ... */ },})
// After (addEventListener)const nv = new NiiVue({})nv.addEventListener('locationChange', (e) => { /* e.detail === data */ })nv.addEventListener('frameChange', (e) => { const { volume, frame } = e.detail})nv.addEventListener('dragRelease', (e) => { /* e.detail === info */ })Key differences:
- Event data is in
e.detail(standardCustomEventpattern) - Listeners can be added/removed at any time, not just at construction
- Multiple listeners per event are supported
- Events with no payload (e.g.
documentLoaded,viewDestroyed) use plainEventinstead ofCustomEvent
Exported Types
All event detail types are exported from the package for use in TypeScript:
import type { NVEventMap, NVEventTarget, FrameChangeDetail, VolumeLoadedDetail, MeshLoadedDetail, VolumeRemovedDetail, MeshRemovedDetail, AzimuthElevationChangeDetail, ClipPlaneChangeDetail, SliceTypeChangeDetail, PenValueChangedDetail, DrawingChangedDetail, DrawingEnabledDetail, PropertyChangeDetail, PointerUpDetail, VolumeUpdatedDetail, MeshUpdatedDetail, ViewAttachedDetail, CanvasResizeDetail, AnnotationAddedDetail, AnnotationRemovedDetail, AnnotationChangedDetail, ColormapAddedDetail, ChunkStreamDetail, ByteLruStats,} from '@niivue/niivue'