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().
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
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 required
-
ChartPointerEventProps
button
required number The index of the button used.
defaultPrevented
required boolean If the default action was prevented.
id
required null | string The id of the target item, or null if not an item.
modifierKeys
requiredA dictionary detailing which modifier keys were pressed when the event occurred.
pointerId
required number The unique identifier of the pointer.
pointerType
required string The type of pointing device as returned by the browser. The standard values are 'mouse', 'touch' and 'pen'.
Call to prevent the event's default action.
Returns
void
x
required number The x location of the pointer in view coordinates.
y
required number The y location of the pointer in view coordinates.
The context-menu event fires on a right click or long press for touch devices.
Default action: Suppresses the click event
Parameters
- event required
-
ChartPointerEventProps
button
required number The index of the button used.
defaultPrevented
required boolean If the default action was prevented.
id
required null | string The id of the target item, or null if not an item.
modifierKeys
requiredA dictionary detailing which modifier keys were pressed when the event occurred.
pointerId
required number The unique identifier of the pointer.
pointerType
required string The type of pointing device as returned by the browser. The standard values are 'mouse', 'touch' and 'pen'.
Call to prevent the event's default action.
Returns
void
x
required number The x location of the pointer in view coordinates.
y
required number The y location of the pointer in view coordinates.
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 required
-
ChartPointerEventProps
button
required number The index of the button used.
defaultPrevented
required boolean If the default action was prevented.
id
required null | string The id of the target item, or null if not an item.
modifierKeys
requiredA dictionary detailing which modifier keys were pressed when the event occurred.
pointerId
required number The unique identifier of the pointer.
pointerType
required string The type of pointing device as returned by the browser. The standard values are 'mouse', 'touch' and 'pen'.
Call to prevent the event's default action.
Returns
void
x
required number The x location of the pointer in view coordinates.
y
required number The y location of the pointer in view coordinates.
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 required
-
DragEventProps
button
required number The index of the button used.
defaultPrevented
required boolean If the default action was prevented.
dragIds
required string[] If type is 'node', 'link' or 'annotation', contains the list of items being dragged.
id
required null | string The id of the target item, or null if not an item.
modifierKeys
requiredA dictionary detailing which modifier keys were pressed when the event occurred.
pointerId
required number The unique identifier of the pointer.
pointerType
required string The type of pointing device as returned by the browser. The standard values are 'mouse', 'touch' and 'pen'.
Call to prevent the event's default action.
Returns
void
type
required "node" | "link" | "annotation" | "pan" | "marquee" | "map" | "resize" | "create-link" | "overview" | "slider" The type of drag.
x
required number The x location of the pointer in view coordinates.
y
required number The y location of the pointer in view coordinates.
The drag-move event fires continuously as the cursor moves during a drag.
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('drag-move',() => {
throttle(eventHandlerFunction, 100);
});Parameters
- event required
-
DragEventProps
button
required number The index of the button used.
defaultPrevented
required boolean If the default action was prevented.
dragIds
required string[] If type is 'node', 'link' or 'annotation', contains the list of items being dragged.
id
required null | string The id of the target item, or null if not an item.
modifierKeys
requiredA dictionary detailing which modifier keys were pressed when the event occurred.
pointerId
required number The unique identifier of the pointer.
pointerType
required string The type of pointing device as returned by the browser. The standard values are 'mouse', 'touch' and 'pen'.
Call to prevent the event's default action.
Returns
void
type
required "node" | "annotation" | "pan" | "marquee" | "map" | "resize" | "link" | "create-link" | "overview" | "slider" The type of drag.
x
required number The x location of the pointer in view coordinates.
y
required number The y location of the pointer in view coordinates.
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 required
-
DragEventProps
button
required number The index of the button used.
defaultPrevented
required boolean If the default action was prevented.
dragIds
required string[] The list of items being dragged.
id
required null | string The id of the item underneath the dragging cursor, or null if over the background.
modifierKeys
requiredA dictionary detailing which modifier keys were pressed when the event occurred.
pointerId
required number The unique identifier of the pointer.
pointerType
required string The type of pointing device as returned by the browser. The standard values are 'mouse', 'touch' and 'pen'.
Call to prevent the event's default action.
Returns
void
type
required "node" | "annotation" The type of item dragged by the cursor.
x
required number The x location of the pointer in view coordinates.
y
required number The y location of the pointer in view coordinates.
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 required
-
DragStartEventProps - options required
button
required number The index of the button used.
defaultPrevented
required boolean If the default action was prevented.
dragIds
required string[] If type is 'node', 'link' or 'annotation', contains the list of items being dragged.
id
required null | string The id of the target item, or null if not an item.
modifierKeys
requiredA dictionary detailing which modifier keys were pressed when the event occurred.
pointerId
required number The unique identifier of the pointer.
pointerType
required string The type of pointing device as returned by the browser. The standard values are 'mouse', 'touch' and 'pen'.
Call to prevent the event's default action.
Returns
void
type
required "node" | "annotation" | "pan" | "marquee" | "map" | "resize" | "link" | "create-link" | "overview" | "slider" The type of drag.
x
required number The x location of the pointer in view coordinates.
y
required number The y location of the pointer in view coordinates.
A function to control the dragging behaviour. See setDragOptions for a list of parameters.
Parameters
Returns
void
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 required
-
ChartPointerEventProps
button
required number The index of the button used.
defaultPrevented
required boolean If the default action was prevented.
id
required null | string The id of the target item, or null if not an item.
modifierKeys
requiredA dictionary detailing which modifier keys were pressed when the event occurred.
pointerId
required number The unique identifier of the pointer.
pointerType
required string The type of pointing device as returned by the browser. The standard values are 'mouse', 'touch' and 'pen'.
Call to prevent the event's default action.
Returns
void
x
required number The x location of the pointer in view coordinates.
y
required number The y location of the pointer in view coordinates.
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 required
-
KeyboardEventProps
defaultPrevented
required boolean If the default action was prevented.
keyCode
required number The keyCode of the key pressed.
modifierKeys
requiredA dictionary detailing which modifier keys were pressed when the event occurred.
Call to prevent the event's default action.
Returns
void
The key-up event fires when the user releases a key.
Default action: None
Parameters
- event required
-
KeyboardEventProps
defaultPrevented
required boolean If the default action was prevented.
keyCode
required number The keyCode of the key pressed.
modifierKeys
requiredA dictionary detailing which modifier keys were pressed when the event occurred.
Call to prevent the event's default action.
Returns
void
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 required
-
ChartLinkAggregationEventProps
aggregateByDirection
required undefined | "both" | "none" | "from" | "to" The arrow direction of the child links, when aggregateByDirection is set to true, undefined otherwise.
aggregateByValue
required any The value of the property being used to group links into aggregate links. It is undefined when aggregateBy is not used.
change
required "created" | "updated" | "deleted" Describes the change occuring to the aggregate link.
id
required string The id for this aggregate link.
id1
required string The id of the node/combo at one end of the aggregate link that comes first in alphanumeric order. This order may be relevant when using aggregate links with sequential layout without top or level specified, or when setting arrows or flow on aggregate links. See Enabling aggregate links.
id2
required string The id of the node/combo at the other end of the aggregate link that comes second in alphanumeric order. This order may be relevant when using aggregate links with sequential layout without top or level specified, or when setting arrows or flow on aggregate links. See Enabling aggregate links.
links
required string[] An array of the ids of the child links.
The map event fires at the start and end of transitions to and from a Leaflet map.
Default action: None
Parameters
The pointer-down event fires when a pointer presses down on the chart.
Default action: None
Parameters
- event required
-
ChartPointerEventProps
button
required number The index of the button used.
defaultPrevented
required boolean If the default action was prevented.
id
required null | string The id of the target item, or null if not an item.
modifierKeys
requiredA dictionary detailing which modifier keys were pressed when the event occurred.
pointerId
required number The unique identifier of the pointer.
pointerType
required string The type of pointing device as returned by the browser. The standard values are 'mouse', 'touch' and 'pen'.
Call to prevent the event's default action.
Returns
void
x
required number The x location of the pointer in view coordinates.
y
required number The y location of the pointer in view coordinates.
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 required
-
ChartPointerEventProps
button
required number The index of the button used.
defaultPrevented
required boolean If the default action was prevented.
id
required null | string The id of the target item, or null if not an item.
modifierKeys
requiredA dictionary detailing which modifier keys were pressed when the event occurred.
pointerId
required number The unique identifier of the pointer.
pointerType
required string The type of pointing device as returned by the browser. The standard values are 'mouse', 'touch' and 'pen'.
Call to prevent the event's default action.
Returns
void
x
required number The x location of the pointer in view coordinates.
y
required number The y location of the pointer in view coordinates.
The pointer-up event fires when the pointer is released.
Default action: None
Parameters
- event required
-
ChartPointerEventProps
button
required number The index of the button used.
defaultPrevented
required boolean If the default action was prevented.
id
required null | string The id of the target item, or null if not an item.
modifierKeys
requiredA dictionary detailing which modifier keys were pressed when the event occurred.
pointerId
required number The unique identifier of the pointer.
pointerType
required string The type of pointing device as returned by the browser. The standard values are 'mouse', 'touch' and 'pen'.
Call to prevent the event's default action.
Returns
void
x
required number The x location of the pointer in view coordinates.
y
required number The y location of the pointer in view coordinates.
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
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 required
-
ProgressEventProps - Organic - Reports incrementally
- Hierarchy - Only reports 0 or 1
- Sequential - Only reports 0 or 1
- Lens - Reports incrementally
- Radial - Only reports 0 or 1
- Structural - Reports incrementally
- Standard - Reports incrementally
progress
required number How near the task is to completion on a scale of 0 to 1, where 0 is just started and 1 is finished. A progress of 1 indicates that the layout has finished computing, but not that the nodes have finished repositioning themselves. Layouts report progress differently depending on the layout used:
task
required string The name of the task.
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);
});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);
});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 required
-
WheelEventProps - 0: Pixels
- 1: Lines
- 2: Pages
defaultPrevented
required boolean If the default action was prevented.
deltaMode
required number The unit of measurement for delta value:
deltaX
required number The number of units that the wheel scrolled in the x direction.
deltaY
required number The number of units that the wheel scrolled in the y direction.
modifierKeys
requiredA dictionary detailing which modifier keys were pressed when the event occurred.
Call to prevent the event's default action.
Returns
void
x
required number The x location of the pointer in view coordinates.
y
required number The y location of the pointer in view coordinates.
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.
meta
required boolean If the meta key was held down when the event occurred. This is the Windows key on Windows and the cmd key on MacOS.
shift
required boolean If a shift key was held down when the event occurred.
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.
string | string[] The ids of nodes and combos to be dragged in addition to selected items.
boolean
default: true Controls if combos should be dragged when child nodes are. Set to false to drag child nodes separately.
boolean
default: true Set to false to disable horizontal dragging.
"pan" | "marquee" | "node" The type of drag.
boolean
default: true Set to false to disable vertical dragging.
Contains details of the sub-item targetted by the event.
number 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.
"t1" | "t2" The end of the link the sub-item is attached to. Only available if type is 'arrowhead', 'glyph' or 'label'.
string The id of the sub-item, e.g. 'ne' or 't'.
string[] When type is 'connection' or 'container', tells you which annotation subjects the connector line points to, or which subjects are present in the annotation container.
"container" | "resize" | "label" | "donut" | "glyph" | "halo" | "bubble" | "arrowhead" | "connection" The type of 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