Skip to main content

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 = jsPlumbBrowserUI.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

Controlling connection detach#

After establishing a connection, you can drag that connection back off the target, 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 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.

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.