Skip to main content

Edges

Edges map the relationship between vertices in your UI. In the data model, an edge consists of a source vertex (node, group or port), a target vertex, and some optional backing data, such as ID, type, label etc.

Bezier connector and PlainArrow overlay

In the UI, an edge is represented by a few concepts that work in tandem:

  • The location of each end of an edge is determined by its source and target anchors
  • The path inscribed by the edge is determined by its connector type, and also by any path edits made by the user
  • The appearance of an edge (its color, width, dashed vs solid etc) is determined by a PaintStyle, or by CSS.
  • The edge may have zero or more overlays, which are adornments that can be placed at any point along the path inscribed by the edge.

By default, JsPlumb will draw every edge in your dataset using the Straight connector, without any overlays. To configure options for an edge you have a couple of possible approaches.

Configuring edge defaults​

You can use the defaults render option to configure connector types and anchors:

Vanilla JS
React
Angular
Vue
Svelte
import { newInstance,
	OrthogonalConnector,
	AnchorLocations } from "@jsplumbtoolkit/browser-ui"

const toolkit = newInstance()
    
const surface = toolkit.render(someElement, {
  "defaults": {
    "connector": OrthogonalConnector.type,
    "anchor": AnchorLocations.Top
  }
});

Mapping edge types in a view​

For more fine-grained control you can map edge types inside a view:

Vanilla JS
React
Angular
Vue
Svelte
import { newInstance,
	OrthogonalConnector,
	AnchorLocations } from "@jsplumbtoolkit/browser-ui"

const toolkit = newInstance()
    
const surface = toolkit.render(someElement, {
  "view": {
    "edges": {
      "redOrthogonal": {
        "connector": OrthogonalConnector.type,
        "anchor": AnchorLocations.Top,
        "paintStyle": {
          "stroke": "red",
          "strokeWidth": 2
        }
      }
    }
  }
});

Events​

You can map various events to edges inside your view, via the events parameter listed above. The list of bindable events is:

export type BindableEvent = "click" | "dblclick" |
                "mouseover" | 
                "mouseout" | 
                "mousedown" | 
                "mouseup" | 
                "tap" | 
                "dbltap" | 
                "contextmenu"
Vanilla JS
React
Angular
Vue
Svelte
import { newInstance } from "@jsplumbtoolkit/browser-ui"

const toolkit = newInstance()
    
const surface = toolkit.render(someElement, {
  "view": {
    "edges": {
      "default": {
        "events": {
          "click": (p:EdgeEventPayload) => { }
        }
      }
    }
  }
});

The definition of EdgeEventPayload is:

export interface EdgeEventPayload {
    edge:Edge,
    e:MouseEvent,
    toolkit: JsPlumbToolkit,
    renderer: Surface,
    connection: Connection
}

Controlling edge detach​

By default, edges are detachable with the mouse, and if an edge is detached and dropped into whitespace it is removed. Both of these behaviours can be controlled in an edge mapping in your view.

Marking edges not detachable​
Vanilla JS
React
Angular
Vue
Svelte
import { newInstance } from "@jsplumbtoolkit/browser-ui"

const toolkit = newInstance()
    
const surface = toolkit.render(someElement, {
  "view": {
    "edges": {
      "default": {
        "detachable": false
      }
    }
  }
});
Reattaching edges dropped in whitespace​
Vanilla JS
React
Angular
Vue
Svelte
import { newInstance } from "@jsplumbtoolkit/browser-ui"

const toolkit = newInstance()
    
const surface = toolkit.render(someElement, {
  "view": {
    "edges": {
      "default": {
        "reattach": true
      }
    }
  }
});

Edge labels​

There are several properties on an edge mapping that you can use to configure labels for your edges - these are discussed on a separate page

Overlays​

Overlays can be added to edges in a few different ways.

info

On this page we show examples of how to attach overlays to edges with several examples. For a full list of all of the available overlays - and their configuration options - see our overlay reference page.

In a view​

An edge mapping in a view can take an overlays parameter which specifies one or more overlays to attach to an edge of that type:

Vanilla JS
React
Angular
Vue
Svelte
import { newInstance,
	ArrowOverlay } from "@jsplumbtoolkit/browser-ui"

const toolkit = newInstance()
    
const surface = toolkit.render(someElement, {
  "view": {
    "edges": {
      "withArrow": {
        "overlays": [
          {
            "type": ArrowOverlay.type,
            "options": {
              "location": 1,
              "width": 8,
              "length": 10
            }
          }
        ]
      }
    }
  }
});

Via PropertyMapping​

PropertyMapping is a mechanism by which JsPlumb determines the type of some edge, and then derives a set of config to apply to that edge at runtime. When an edge is updated, any property mapping that is active is run again, and the edge updated in the UI accordingly.

PropertyMapping is discussed on a separate page.

Edge options list​

The full list of allowed values inside an edge mapping are:

Interface ViewEdgeOptions

NameTypeDescription
anchor?AnchorSpecSpec for the anchor to use for both source and target for edges of this type.
anchors?[source, target] anchor specs edges of this type.
avoidVertices?booleanIf true, the edge will be routed to avoid any vertices. You must be using the Straight connector for this to work. Note also that if your edge has any user edits, or was loaded with a path specified, the edge will not be routed to avoid vertices.
connector?ConnectorSpecName/definition of the connector to use. If you omit this, the default connector will be used.
cssClass?stringCSS class to add to edges of the type in the UI
deleteButton?Optional delete button.
deleteButtonClass?stringOptional class name to set on the delete button. Defaults to "jtk-edge-delete".
deleteButtonLocation?Location for an edge's delete button, if applicable. Defaults to 0.1. You can supply an array of locations if you want multiple buttons.
deleteConfirm?EdgeDeleteConfirmationFunctionAn optional function to invoke if the user presses the delete button on some edge. When this is present and the user clicks an edge delete button, instead of just deleting the edge, this function is invoked. It is passed the edge that is a candidate for deletion, and a function which you must invoke if you wish to proceed.
detachable?booleanWhether or not edges of this type should be detachable with the mouse. Defaults to true.
endpoint?EndpointSpecOptional spec to use for both the source and target endpoints for edges of this type.
endpointHoverStyle?EndpointStyleOptional paint style to use for hover on both the source and target endpoints for edges of this type.
endpointHoverStyles?Optional paint style to use for hove on the [source, target] endpoints for edges of this type.
endpoints?Optional specs for the [source, target] endpoints for edges of this type.
endpointStyle?EndpointStyleOptional paint style to use for both the source and target endpoints for edges of this type.
endpointStyles?Optional paint styles to use for the [source, target] endpoints for edges of this type.
events?ViewEventOptionsOptional map of event bindings.
hoverPaintStyle?PaintStylePaint style to use for the edge when the pointer is hovering over it.
label?stringOptional label to use for the edge. If this is set, a label overlay will be created and the value of label will be used as the overlay's label. This value can be parameterised, in order to extract a value from the edge's backing data, eg. if you set label:"{{name}}" then the Toolkit would attempt to extract a property with key name from the edge's backing data, and use that property's value as the label.
labelClass?stringOptional css class to set on the label overlay created if label is set. This is a static string and does not support parameterisation like label does.
labelLocation?numberOptional location for the label. If not provided this defaults to 0.5, but the label location can be controlled via the labelLocationAttribute.
labelLocationAttribute?stringThis defaults to labelLocation, and indicates the name of a property whose value can be expected to hold the location at which the label overlay should be located. The default value for this is labelLocation, but the key here is that the Toolkit looks in the edge data for labelLocation, so the location is dynamic, and can be changed by updating labelLocation. This parameter allows you to change the name of the property that the Toolkit will look for in the edge data.
mergeStrategy?stringWhen merging a type description into its parent(s), values in the child for connector, anchor and anchors will always overwrite any such values in the parent. But other values, such as overlays, will be merged with their parent's entry for that key. You can force a child's type to override _every_ corresponding value in its parent by setting mergeStrategy:'override'.
outlineWidth?numberOptional width of the edge's outline. Defaults to 0.
overlays?Array<OverlaySpec>Array of overlays to add to edges of this type.
paintStyle?PaintStylePaint style to use for the edge.
parent?Optional ID of one or more edge definitions to include in this definition. The child definition is merged on top of the parent definition(s). Circular references are not allowed and will throw an error.
reattach?booleanWhether or not when a user detaches a edge of this type it should be automatically reattached. Defaults to false.
useHTMLLabel?booleanBy default, an SVG element will be used for an edge's label overlay. This is good because the label can be exported as part of an SVG export of your canvas. If you wish to use an HTML element instead, set this flag.