Events

JsPlumb offers a rich event driven API that allows you to hook deeply into its functionality and lifecycle. Events can be broken into two broad categories:

Model events Events fired by the JsPlumb Toolkit model, such as the addition/removal of nodes, groups, ports and edges, data load/end lifecycle events, undo/redo etc. Read more below.
UI Events Events fired by JsPlumb's UI components, such as node dragging, mouse interactions, and much more.

Model events

Model events are fired by instances of JsPlumbToolkit, and pertain to changes in the data model. UI events, discussed below, are fired by the Surface component and its plugins, and pertain to changes in the UI. In some cases the Surface component will fire the same event as its associated Toolkit instance - for example, a Toolkit instance fires a node:removed event, which the Surface receives; the Surface updates the UI as necessary, and then itself fires a node:removed event, but with a slightly different payload. There are also other UI specific events which the Toolkit does not fire, such as those associated with dragging a vertex, or changing the zoom.

JsPlumb also supports binding event handlers to nodes, groups, ports and edges - you can declare event handlers on a per-type basis for each of your model objects. For more information, take a look at the views documentation.

Model events can be bound using the bind method on an instance of JsPlumbToolkit. In Typescript the bind method takes an optional generic parameter, which we encourage you to set (according to the values given on this page). An example:

Vanilla JS

React

Angular

Vue

Svelte

import { newInstance } from "@jsplumbtoolkit/browser-ui"

const toolkit = newInstance()
    
const surface = toolkit.render(someElement, {});
toolkit.bind(EVENT_NODE_ADDED, (p:NodeAddedParams) => {
  console.log(`Node with ID ${p.node.id} was added`)  
})
                                          
toolkit.addNode({id:"foo"})

Event List

Events fired by the JsPlumb model

Event	Constant	Description	Payload
`port:added`	EVENT_PORT_ADDED	Fired when a port has been added to some node/group	PortAddedParams
`port:removed`	EVENT_PORT_REMOVED	Fired whenever a port is removed from some node or group.	PortRemovedParams
`port:updated`	EVENT_PORT_UPDATED	Fired whenever the data model for a port changes	PortUpdatedParams
`node:added`	EVENT_NODE_ADDED	Fired whenever a new node is added to the data model	NodeAddedParams
`node:removed`	EVENT_NODE_REMOVED	Fired when a node has been removed from the dataset	NodeRemovedParams
`node:updated`	EVENT_NODE_UPDATED	Fired whenever a node's data is updated	VertexUpdatedParams
`group:added`	EVENT_GROUP_ADDED	Fired whenever a new group is added to the data model	GroupAddedParams
`group:removed`	EVENT_GROUP_REMOVED	Fired when a group has been removed from the dataset	GroupRemovedParams
`group:updated`	EVENT_GROUP_UPDATED	Fired whenever a group's data is updated	VertexUpdatedParams
`group:member:added`	EVENT_GROUP_MEMBER_ADDED	Fired when a node/group has been added to a group	GroupMemberAddedParams
`group:member:removed`	EVENT_GROUP_MEMBER_REMOVED	Fired when a node/group has been removed from a group	GroupMemberRemovedParams
`edge:added`	EVENT_EDGE_ADDED	Fired whenever a new edge is added to the data model	EdgeAddedParams
`edge:updated`	EVENT_EDGE_UPDATED	Fired whenever the data model for an edge changes	EdgeUpdatedParams
`edge:removed`	EVENT_EDGE_REMOVED	Fired when an edge is removed	EdgeRemovedParams
`edge:target`	EVENT_EDGE_TARGET_CHANGED	Fired when the target for some edge has changed	EdgeTargetChangedParams
`edge:source`	EVENT_EDGE_SOURCE_CHANGED	Fired when the source for some edge has changed	EdgeSourceChangedParams
`edge:pathEdited`	EVENT_EDGE_PATH_EDITED	Fired when the path for some edge has changed	EdgePathEditedParams
`undoredo:update`	EVENT_UNDOREDO_UPDATE	Fired when the undo/redo manager changes state	UndoRedoUpdateParams
`selection:cleared`	EVENT_SELECTION_CLEARED	Fired when a Toolkit instance's current selection is cleared	{selection:Selection}
`graphClearStart`	EVENT_GRAPH_CLEAR_START	Fired when the `clear()` method has been called, but before the data has been cleared
`graphCleared`	EVENT_GRAPH_CLEARED	Fired after the data has been cleared by the `clear()` method
`dataLoadStart`	EVENT_DATA_LOAD_START	Fired immediately prior to some data being loaded
`dataLoadEnd`	EVENT_DATA_LOAD_END	Fired immediately after some data was loaded
`select`	EVENT_SELECT	Fired when some object is added to the Toolkit's current selection. The `append` flag in the payload indicates whether or not the given object was appended to the selection or if it replaced the previous selection	{append: boolean,obj: Node\|Group\|Edge, selection: Selection}
`deselect`	EVENT_DESELECT	Fired when some object is removed from the Toolkit's current selection	{obj: Node\|Group\|Edge, selection: Selection}

UI Events

These events are fired by the Surface widget. Note that some of these events are also fired by the underlying Toolkit, but the surface payload provides the related UI element information.

Binding to Surface events

Event listeners can be bound to the surface widget in one of three ways:

via the bind method
in the events parameter to a render call on an instance of the Toolkit
in the individual Node, Group, Port and Edge definitions in the view parameter to a render call.

The full list of bindable events is listed below.

Using bind

With this approach, you have an instance of the surface component and you register event listeners via its bind method:

Vanilla JS

React

Angular

Vue

Svelte

import { newInstance } from "@jsplumbtoolkit/browser-ui"

const toolkit = newInstance()
    
const surface = toolkit.render(someElement, {});
surface.bind("canvasClick", (e) => {
  console.log("click on the canvas");
  });
                                          
 surface.bind("node:added", (params) => {
                                           
 });

Declarative binding

Each of the entries in the events block is equivalent to first instantiating the surface and then calling bind on it.

Vanilla JS

React

Angular

Vue

Svelte

import { newInstance,
	EVENT_NODE_ADDED,
	EVENT_CANVAS_CLICK } from "@jsplumbtoolkit/browser-ui"

const toolkit = newInstance()
    
const surface = toolkit.render(someElement, {
  "events": {
    [EVENT_CANVAS_CLICK]: (e) => {
    console.log(\click on the canvas\");
  }",
    [EVENT_NODE_ADDED]: (params) => {}
  }
});

Suspending Events

You can suspend/enable events from the surface widget with this method:

surface.setSuspendEvents(true);

You can also wrap the underlying Toolkit's batch command (which runs a series of operations without making any rendering changes) with the surface widget's batch command:

surface.batch(() => {
  toolkit.addNode({id:"foo"});
  toolkit.addNode({id:"bar"});
  toolkit.addNode({source:"foo", target:"bar"});
});

This is equivalent to:

surface.setSuspendEvents(true);
toolkit.batch(() => {
  toolkit.addNode({id:"foo"});
  toolkit.addNode({id:"bar"});
  toolkit.addNode({source:"foo", target:"bar"});
});
surface.setSuspendEvents(false);

Surface Events

This is the full list of events fired by the Surface component.

Event	Constant	Description	Payload
`node:added`	EVENT_NODE_ADDED	Fired whenever a new node is added to the data model	SurfaceVertexAddedParams
`group:added`	EVENT_GROUP_ADDED	Fired whenever a new node is added to the data model	SurfaceVertexAddedParams
`group:removed`	EVENT_GROUP_REMOVED	Fired when a group is removed	SurfaceGroupRemovedParams
`group:resized`	EVENT_GROUP_RESIZE	Fired when a group has been resized	SurfaceGroupResizedParams
`edge:added`	EVENT_EDGE_ADDED	Fired when a new edge has been added	SurfaceEdgeAddedParams
`pan`	EVENT_PAN	Fired when the surface has just been panned	SurfacePanZoomParams
`zoom`	EVENT_ZOOM	Fired when the surface's zoom has just changed	SurfacePanZoomParams
`node:move:start`	EVENT_NODE_MOVE_START	Fired when a node/group has just begun to be dragged	SurfaceVertexMoveStartParams
`node:move`	EVENT_NODE_MOVE	Fired continuously while a node/group is being dragged	VertexMovedParams
`node:move:end`	EVENT_NODE_MOVE_END	Fired when a node has just been dragged	VertexMovedParams
`group:move:end`	EVENT_GROUP_MOVE_END	Fired when a group has just been dragged	VertexMovedParams
`modeChanged`	EVENT_SURFACE_MODE_CHANGED	Fired when the mode for a surface was changed	SurfaceMode
`destroy`	EVENT_DESTROY	Fired when a surface has been destroyed	Surface
`group:collapse`	EVENT_GROUP_COLLAPSE	Fired when a group has been collapsed	SurfaceGroupCollapsedParams
`group:expand`	EVENT_GROUP_EXPAND	Fired when a group has been expanded	SurfaceGroupExpandedParams
`startOverlayAnimation`	EVENT_START_OVERLAY_ANIMATION	Fired at the beginning of a path traversal	Connection
`endOverlayAnimation`	EVENT_END_OVERLAY_ANIMATION	Fired at the very end of a path traversal
`startNodeTraversal`	EVENT_START_NODE_TRAVERSAL	Fired when a node/group has been reached and is being traversed
`endNodeTraversal`	EVENT_END_NODE_TRAVERSAL	Fired at the end of traversing a node/group

Model events​

Event List​

UI Events​

Binding to Surface events​

Using bind​

Declarative binding​

Suspending Events​

Surface Events​

Model events

Event List

UI Events

Binding to Surface events

Using bind

Declarative binding

Suspending Events

Surface Events