Connectivity

There are two ways to connect elements with jsPlumb - programmatically, via the API, and also with the mouse. This page discusses both approaches.

Programmatic connections

The most simple connection you can make with jsPlumb looks like this:

instance.connect({source:element1, target:element2})

In this example we have created a connection from element1 to element2. Remember that a connection in jsPlumb consists of two endpoints, a connector, and zero or more overlays. But this call to connect supplied none of those things, so jsPlumb uses the default values wherever it needs to. In this case, default values have been used for the following:

• The type and appearance of each endpoint in the connection. jsPlumb's default for this is the Dot endpoint, of radius 5
• The anchors that define where the connection's endpoints appear on each element. The jsPlumb default is Bottom.
• Whether or not each endpoint can be a source or target for new connections. The default is false.
• The type and appearance of the connection's connector. The default is a "Bezier" connector of line width 8.

So this call will result in an 8px Bezier from the bottom center of element1 to the bottom center of element2, and each endpoint will be a Dot endpoint with radius 5 pixels.

Let's beef up this call a little and tell jsPlumb what sort of endpoints we want, and where we want them:

instance.connect({  source:element1,   target:element2,  anchors:["Right", "Left" ],  endpoint:"Rectangle"});

This is what we have told jsPlumb we want this time:

• anchors - this array tells jsPlumb where the source and target endpoints should be located on their parent elements. In this case, we use the shorthand syntax to name one of jsPlumb's default anchors; you can also specify custom locations (see Anchors. Instead of anchors you can use anchor, if you want the source and target endpoints to be located at the same place on their parent elements.
• endpoint - this tells jsPlumb to use the Rectangle endpoint for both the source and target of the connection. As with anchors, endpoint has a plural version that allows you to specify a different endpoint for each end of the connection.

Endpoints created by connect

If you supply an element id or selector for either the source or target, connect will automatically create an endpoint on the given element. These automatically created endpoints are not marked as drag source or targets, and cannot be interacted with. For some situations this behaviour is perfectly fine, but for more interactive UIs you should set things up using one of the drag and drop methods discussed below.

Note: given that connect(..) creates its own endpoints in some circumstances, in order to avoid leaving orphaned endpoints around the place, if the connection is subsequently deleted, these automatically created endpoints are deleted too. Should you want to, you can override this behaviour by setting deletEendpointsOnDetach to false in the connect call:

instance.connect({   source:aThirdElement,   target:"etAnotherElement,  deleteEndpointsOnDetach:false });

Detaching connections

By default, connections made with connect(..) will be detachable via the mouse. You can prevent this by either setting an appropriate default value when you construct an instance of jsPlumb:

const instance = jsPlumb.newInstance({   ...  connectionsDetachable:false  ...});

or by subsequently setting the default on an existing instance of jsPlumb:

instance.importDefaults({   ...  connectionsDetachable:false  ...});

...or by specifying it on the connect call like this:

instance.connect({   source:aThirdElement,   target:yetAnotherElement,  detachable:false});

---

Drag and drop connections

Connections can be established using the mouse between any combination of endpoints and elements. We'll first discuss setting up endpoints on your elements to use as drag/drop target.

Configuring endpoints

Here's a simple example of how to create an endpoint:

var sourceEndpoint = instance.addEndpoint(element, {    source:true,    endpoint:"Dot"    });

This endpoint will act as a source for new connections, and will use the jsPlumb defaults for its own appearance and that of any connections that are drawn from it. This endpoint will not act as a target for connections established with the mouse, because we did not set target:true on its parameters:

var targetEndpoint = instance.addEndpoint(element, {    target:true,     endpoint:"Rectangle"    });

...now we have a source and a target endpoint. You can drag a connection from the source to the target, but not vice versa. Try it out here:

Drag/drop with endpoints

Disabling connection detach

After establishing a connection, you can drag that connection back off the target (and the source), because that's the default behaviour. If instead we defined the source endpoint like this:

var sourceEndpoint = instance.addEndpoint(element, {    source:true,    endpoint:"Dot",    connectionsDetachable: false    });

then we would not be able to drag the connection off:

Endpoint with connectionsDetachable:false

Reattaching connections

You might want to setup your endpoints in such a way that a connection can be detached from some endpoint, and if it is dropped in whitespace, it should subsequently be reattached. You can do this with the reattachConnections flag:

var sourceEndpoint = instance.addEndpoint(element, {    source:true,    endpoint:"Dot",    reattachConnections: true    });

Endpoint with reattachConnections:true

In this example you can detach the connection from node 2 and drop it on node 3, but if you drop it in whitespace it will reattach to the node it was previously connected to.

---

Configuring elements

jsPlumb supports registering CSS selectors that identify elements, or parts thereof, that can act as sources and targets for dragging connection with the mouse. For those familiar with earlier versions of jsPlumb, this concept is analogous to the makeSource and makeTarget methods, but in 5.x/6.x the approach uses delegated event handlers and is more flexible and performant.

A simple example first:

instance.addSourceSelector(".sourcePlaceholder", {    endpoint:"Rectangle",    anchor:"Continuous"})
instance.addTargetSelector(".targetPlaceholder", {    anchor:"Continuous"})

Simple source/target selector example

In this example you can drag connections from the red circles and drop them on the green circles. The connections themselves are established between the DOM elements - these circles are not endpoints as above. They are parts of the DOM element that we have designated to have a specific function. Note that when you use `addSourceSelector` to register a source selector on a jsPlumb instance, that selector is automatically added to the list of selectors from which drag is excluded. In the example above you can drag both elements around by any part of the element except the red circles.

These methods honour the jsPlumb defaults - if, for example you set up the default Anchors to be this:

instance.importDefaults({  anchors : [ "Left", "BottomRight" ]});

... and then used addSourceSelector and addTargetSelector without specifying anchor locations, jsPlumb would use Left for the source element and BottomRight for the target element.

Retaining endpoints when detaching connections

By default, any endpoints created using addTargetSelector have deleteEndpointsOnDetach set to true, which means that once all connections to that endpoint are removed, the endpoint is deleted. You can override this by setting the flag to true on the addTargetSelector call:

var endpointOptions = {   target:true,   maxConnections:5,  uniqueEndpoint:true,  deleteEndpointsOnDetach:false,  endpoint:"Rectangle" };instance.addTargetSelector(".someSelector", endpointOptions);

In this setup we have told jsPlumb to create an endpoint the first time aTargetElement receives a connection, and to not delete it even if there are no longer any connections to it. The created endpoint will be reused for subsequent connections, and can support a maximum of 5.

Reattaching connections

As with addEndpoint, addSourceSelector supports both the connectionsDetachable and the reattachConnections flags. For instance, drag from the red circle to the green circle here and then try to detach the connection with the mouse. You will not be able to detach the connections because connectionsDetachable is set to false:

Preventing connection detach

instance.addSourceSelector(".sourcePlaceholder", {    endpoint:"Rectangle",    anchor:"AutoDefault",    connectionsDetachable:false})
instance.addTargetSelector(".targetPlaceholder", {    anchor:"AutoDefault"})

addSourceSelector connectionsDetachable:false

Reattaching detached connections

With reattachConnections:true you can instruct jsPlumb to automatically reattach connections that have been dropped in whitespace:

instance.addSourceSelector(".sourcePlaceholder", {    endpoint:"Rectangle",    anchor:"AutoDefault",    reattachConnections:true})
instance.addTargetSelector(".targetPlaceholder", {    anchor:"AutoDefault"})

addSourceSelector connectionsDetachable:false

Redrop policies

A more granular approach to controlling where existing connections can be dragged and dropped is the concept of a RedropPolicy. By default, the policy is "strict", meaning a connection can only be dropped onto a source or target selector that matches the source or target selector that originally created the endpoint that is being dragged. But there are a few different values for this (see table below). For instance, a value of "any" allows you to drop a connection on any part of an element that has a selector defined on it:

instance.addSourceSelector(".sourcePlaceholder", {    endpoint:"Rectangle",    anchor:"AutoDefault",    redrop:"any"})
instance.addTargetSelector(".targetPlaceholder", {    anchor:"AutoDefault"})

REDROP_POLICY_ANY

Drag a connection from a red dot to a green dot, and then detach the connection from its source element. You can drop the source endpoint on any of the elements:

RedropPolicy 'any'

REDROP_POLICY_STRICT

For comparison, here's the same setup but with the default redrop policy of "strict". Drag a connection from a red dot to a green dot, and then detach the connection from its source element. You can only drop the source endpoint onto one of the red dots:

RedropPolicy 'strict'

Redrop Policy Values

Constant	Value	Description
REDROP_POLICY_STRICT	strict	The default. Connections can only be dropped onto a part of a source/target element that is specifically configured as a source or target selector
REDROP_POLICY_ANY	any	Connections can be dropped onto any element for which either the element itself or one of its children is configured as a source or target selector
REDROP_POLICY_ANY_SOURCE	anySource	For source selectors, stipulates that a connection can be dropped onto any element that is configured as a source or for which one of its children is configured as a source
REDROP_POLICY_ANY_TARGET	anyTarget	For target selectors, stipulates that a connection can be dropped onto any element that is configured as a target or for which one of its children is configured as a target
REDROP_POLICY_ANY_SOURCE_OR_TARGET	anySourceOrTarget	Stipulates that a connection can be dropped onto any element that is configured as a target or source or for which one of its children is configured as a source or target