Chart Events

Events let you customise your application by responding to user actions on the chart surface. To attach handlers to events, use chart.on().

all

The 'all' event fires when any event occurs on the chart.

It returns an object containing both the name of the event and the object returned by that event.

Parameters

props: ChartAllEvent

click

The click event fires on a click or tap.

Default action:

On an item: Selects the item (adds to current selection if consistentCtrl is pressed)
On the background: Deselects all items
On the navigation controls: Performs the navigation control action
On the overview icon: Opens or closes the overview window

Parameters

event: ChartPointerEventProps

The context-menu event fires on a right click or long press for touch devices.

Default action: Suppresses the click event

Parameters

event: ChartPointerEventProps

double-click

The double-click event fires on a double click or double tap.

Default actions:

On the background: Zooms in (animated)
On a combo: Opens or closes the combo

Parameters

event: ChartPointerEventProps

drag-end

The drag-end event fires when the drag is finished and pointer is released, or when the drag is cancelled. On touch devices this fires when the finger or pointing device is lifted from the surface.

Default actions:

Updates the chart selection if type is 'marquee'
Moves selected items to their final positions if type is 'node' or 'link'
Accepts the final viewport position if type is 'pan' or 'overview'
Creates the link if type is 'create-link'

Parameters

event: DragEventProps

drag-over

The drag-over event fires when the cursor dragging a node or an annotation moves over another item during a drag.

Default action: None

Parameters

event: DragEventProps

drag-start

The drag-start event fires when a drag is started.

Default action: Creates a dragger. Use setDragOptions to set the drag behaviour:

// pan the chart with the right mouse button
chart.on('drag-start', ({ setDragOptions, button }) => {
  if (button === 2) {
    setDragOptions({ type: 'pan' });
  }
});

Parameters

event: DragStartEventProps

hover

The hover event fires when the cursor hovers over an item or the chart background. The event only fires once when the hover id changes.

Pass the hover property to chart.options() to configure the hover delay.

Default action: None

Parameters

event: ChartPointerEventProps

key-down

The key-down event fires when the user presses a key.

Default actions:

Escape key: Cancels a drag if present
Delete key: Deletes selected items
consistentCtrl + A: Selects all selectable items
Arrow keys: Moves selected items

Parameters

event: KeyboardEventProps

key-up

The key-up event fires when the user releases a key.

Default action: None

Parameters

event: KeyboardEventProps

link-aggregation

The link-aggregation event fires each time an aggregate link is created, deleted or updated.

The update occurs when a child link is added, removed, hidden or unhidden, a child link's arrow changes, or when the custom property in d object used for aggregating links is changed.

You can use the event to style aggregate links. The default styling is the same as for a regular link, i.e. a grey link with a width of 1.

To style an aggregate link, use chart.setProperties() in the event handler, providing the id of the aggregate link from the event props:

chart.on('link-aggregation', ({ id }) => {
  chart.setProperties({ id, c: 'blue' })
});

Aggregate links do not inherit any styling from their child links with the exception of arrows.

Note that you must call chart.on before loading the chart data (so that the handler is called when the data is first loaded).

Default action: None

Parameters

event: ChartLinkAggregationEventProps

map

The map event fires at the start and end of transitions to and from a Leaflet map.

Default action: None

Parameters

event: MapEventProps

pointer-down

The pointer-down event fires when a pointer presses down on the chart.

Default action: None

Parameters

event: ChartPointerEventProps

pointer-move

The pointer-move event fires continuously as the pointer moves on the chart.

Default action: None

Use debouncing or throttling to limit the number of times the event handler is called:

let timer;
function throttle(func, delay) {
  if (timer) return;
  timer = setTimeout(() => {
    func();
    timer = undefined;
  }, delay);
}
// throttle eventHandlerFunction to only run once every 100ms
chart.on('pointer-move',() => {
  throttle(eventHandlerFunction, 100);
});

Parameters

event: ChartPointerEventProps

pointer-up

The pointer-up event fires when the pointer is released.

Default action: None

Parameters

event: ChartPointerEventProps

prechange

The prechange event fires whenever the chart changes by either a user action, such as dragging items, or programmatically by calling API methods.

Note that prechange fires before the chart changes. This allows control over state which is useful for adding features like undo/redo.

Default action: None

Parameters

event: PrechangeEventProps

progress

The progress event fires during longer tasks such as layouts and centrality calculations.

Default action: None

chart.on('progress', ({ task, progress }) => {
  if (task === 'layout') {
    // use progress value for something
  }
});

Parameters

event: ProgressEventProps

selection-change

The selection-change event fires when the chart selection changes from a click event or marquee drag. Note that it does not fire if the selection changes programmatically.

Use chart.selection() to find any changes.

Default action: None

Use debouncing or throttling to limit the number of times the event handler is called:

let timer;
function throttle(func, delay) {
  if (timer) return;
  timer = setTimeout(() => {
    func();
    timer = undefined;
  }, delay);
}
// throttle eventHandlerFunction to only run once every 100ms
chart.on('selection-change',() => {
  throttle(eventHandlerFunction, 100);
});

view-change

The view-change event fires continuously during any change to the view such as zoom or pan. It also fires when the view state is changed programmatically.

Use viewOptions to find any changes.

Default action: None

Use debouncing or throttling to limit the number of times the event handler is called:

let timer;
function throttle(func, delay) {
  if (timer) return;
  timer = setTimeout(() => {
    func();
    timer = undefined;
  }, delay);
}
// throttle eventHandlerFunction to only run once every 100ms
chart.on('view-change',() => {
  throttle(eventHandlerFunction, 100);
});

wheel

The wheel event fires continuously while the user is rotating a mouse wheel or scrolling using a trackpad.

Default action:

On the background: Zooms in or out

Parameters

event: WheelEventProps

ModifierKeys

A dictionary detailing which modifier keys were pressed when the event occurred.

alt

required

boolean

If an alt key was held down when the event occurred.

consistentCtrl

required

boolean

If a consistent control key was held down when the event occurred (i.e. cmd key on MacOS and ctrl key on other OS).

ctrl

required

boolean

If a control key was held down when the event occurred.

shift

required

boolean

If a shift key was held down when the event occurred.

setDragOptions

Options to control the dragging behaviour. This function is returned by the drag-start event and is not available in the main chart namespace.

Pass in options as a single object:

// set dragger to marquee when started on a link
function dragStartHandler({ type, setDragOptions }) {
  if (type === 'link') {
    setDragOptions({ type: 'marquee' });
  }
};

chart.on('drag-start', dragStartHandler);

See the Custom Dragging demo for more examples of use.

alsoDrag

string | string[]

The ids of nodes and combos to be dragged in addition to selected items.

dragCombos

booleandefault: true

Controls if combos should be dragged when child nodes are. Set to false to drag child nodes separately.

horizontalMovement

booleandefault: true

Set to false to disable horizontal dragging.

type

"pan" | "marquee" | "node"

The type of drag.

verticalMovement

booleandefault: true

Set to false to disable vertical dragging.

SubItem

Contains details of the sub-item targetted by the event.

When the type of sub-item is 'label', 'glyph' or 'donut', specifies which label, glyph or donut segment in the array to access, e.g. node.t[index], link.g[index] or node.donut.v[index] respectively. Note that 'index' is not required when there is only one 'label' sub-item.

'donut', 'halo' - node decorations
'bubble' - node and link decoration
'label', 'glyph' - node, link and annotation decoration
'resize' - resize handles on open combos
'arrowhead' - arrows on link ends
'container' - the container surrounding annotation subjects
'connection' - the line and subject end of the annotation connector