Handling Events

Nodus emits events as the graph and camera change. Subscribe to them through nodus.events. This guide covers the verified event names, the subscription methods, and where to find pointer interactions (click and hover), which live on the tooltip tool rather than the generic event bus.

For the full method list, see API: Interaction.

Subscribing and unsubscribing

nodus.events is an emitter. The core methods:

// Subscribe.
nodus.events.on('addNodes', (payload) => {
  console.log('nodes added', payload);
});

// Subscribe once — auto-removed after the first emission.
nodus.events.once('clearGraph', () => {
  console.log('graph cleared');
});

// Unsubscribe all handlers for an event.
nodus.events.off('addNodes');

on, off, and once each return the emitter, so calls chain.

Verified events

These are the event names Nodus is confirmed to emit. Build against these; treat anything not listed here as unverified.

Structural changes

Fired as the graph’s contents change.

Event	When it fires
addNodes	One or more nodes were added
addEdges	One or more edges were added
removeNodes	One or more nodes were removed
removeEdges	One or more edges were removed
clearGraph	The whole graph was cleared

nodus.events.on('addNodes', () => updateNodeCounter());
nodus.events.on('removeNodes', () => updateNodeCounter());
nodus.events.on('clearGraph', () => resetUi());

// These now trigger the handlers above.
nodus.addNodes([{ id: 'x' }, { id: 'y' }]);
await nodus.removeNode('x');

Camera movement

The camera emits move as the view pans, zooms, or rotates — useful for keeping DOM overlays aligned with the graph.

nodus.events.on('move', () => {
  // Re-position an HTML label pinned to a node.
  const p = nodus.view.graphToScreenCoordinates(nodus.getNode('ada').getPosition());
  label.style.transform = `translate(${p.x}px, ${p.y}px)`;
});

Attribute updates

updateAttributes fires when element visual attributes change — handy for mirroring style state into your own UI.

nodus.events.on('updateAttributes', () => {
  refreshInspectorPanel();
});

Class events

When a style class is added to or removed from elements, Nodus emits dedicated events. Subscribe with these methods on nodus.events:

// Nodes.
nodus.events.onNodesClassAdded((payload) => {
  console.log('class added to nodes', payload);
});
nodus.events.onNodesClassRemoved((payload) => {
  console.log('class removed from nodes', payload);
});

// Edges.
nodus.events.onEdgesClassAdded((payload) => { /* ... */ });
nodus.events.onEdgesClassRemoved((payload) => { /* ... */ });

These fire as you call element.addClass(...) / removeClass(...) (and the broadcast forms on a list). See Styling Nodes & Edges for how classes are defined and applied.

Keyboard

onKeyPress(key, handler) binds a handler to a key — convenient for shortcuts.

nodus.events.onKeyPress('f', () => {
  nodus.view.locateGraph({ duration: 400 }); // press "f" to fit
});

nodus.events.onKeyPress('Escape', () => {
  nodus.clearSelection();
});

Pointer interactions: click and hover

Click and hover on nodes, edges, and the background are not generic events — they’re handled by the tooltip tool, which also manages an optional tooltip element. Register handlers through nodus.tools.tooltip:

// Click a node.
nodus.tools.tooltip.onNodeClick((node) => {
  node.setSelected(true);
});

// Hover a node — show a tooltip built from your data.
nodus.tools.tooltip.onNodeHover((node) => {
  nodus.tools.tooltip.show(`<strong>${node.getData('name')}</strong>`);
});

// Hovering away — hide it.
nodus.tools.tooltip.onNodeHover(() => {}); // handler also fires on leave per options

// Click empty space.
nodus.tools.tooltip.onBackgroundClick(() => {
  nodus.clearSelection();
});

The tooltip tool also provides onNodeRightClick, onNodeDoubleClick, the edge equivalents (onEdgeClick, onEdgeHover, onEdgeRightClick, onEdgeDoubleClick), and background variants. Its display methods are show, hide, isShown, and refresh. The full treatment — including the connect, lasso, and selection tools — is in Interaction Tools.

Try it live — hover and click the nodes to fire the pointer handlers and tooltip:

Pointer handlers & tooltips Open in new tab ↗

A combined example

Wire structural events, camera sync, and pointer handlers together:

import { Nodus } from '@kortexya/nodus';

const nodus = new Nodus({ container: document.getElementById('graph') });

// Keep a live count as the graph changes.
function updateCounter() {
  counterEl.textContent = `${nodus.getNodes().size} nodes`;
}
nodus.events.on('addNodes', updateCounter);
nodus.events.on('removeNodes', updateCounter);
nodus.events.on('clearGraph', updateCounter);

// Select on click, clear on background click.
nodus.tools.tooltip.onNodeClick((node) => node.setSelected(true));
nodus.tools.tooltip.onBackgroundClick(() => nodus.clearSelection());

// Fit on "f".
nodus.events.onKeyPress('f', () => nodus.view.locateGraph({ duration: 400 }));

await nodus.setGraph({
  nodes: [{ id: 'a' }, { id: 'b' }],
  edges: [{ source: 'a', target: 'b' }],
});
updateCounter();

Next steps

• Go deeper on pointer handlers and tools in Interaction Tools.
• Drive the camera in response to events with Controlling the Camera.
• Define the class styles that class events report on in Styling Nodes & Edges.