Overlays

Overlays are adornments to connections - such things as arrows at the end of a line, or a label, etc. The Toolkit ships with a few types of overlay:

• Arrow - a configurable arrow that is painted at some point along the connector. You can control the length and width of the Arrow, the 'foldback' point - a point the tail points fold back into, and the direction (allowed values are 1 and -1; 1 is the default and means point in the direction of the connection)
• Label - a configurable label that is painted at some point along the connector.
• PlainArrow - an Arrow shaped as a triangle, with no foldback.
• Diamond - A diamond shaped overlay.
• Custom - allows you to create the overlay yourself - your overlay may be any DOM element you like.

PlainArrow and Diamond are actually just configured instances of the generic Arrow overlay (see examples).

Configuring overlays

Overlays can be configured in a few different places:

• As part of the default values in the render params for a surface. Overlays defined here will be applied to every edge in the UI.
• As part of an edge definition inside a view. Overlays defined inside edge definitions will appear on edges of that specific type (or on edges whose type declares that type as a parent)
• In a UI State. A UI state is a way for you to apply a specific configuration to some object on demand.
• In a Property Mapping. A property mapping is a way for you to instruct the surface to configure displayed edges based upon the values of one or more properties in their backing data.

The structure of an overlay specification can take one of two forms - the simplest is just to specify the overlay type by name:

overlays:[
    "Arrow"    
]

but there is very little you can do with this, since the overlay will use its default values and be placed at the default location (halfway along the path travelled by the underlying connector). The second way - and the way you'll almost always use - is to specify the overlay by name and to also provide some configuration values:

overlays:[    
    {
        type:"Arrow",
        options:{
            width:10,
            length:15,
            location:1
        }
    }   
]

Here, we've specified an Arrow overlay with a given width and length, and to be located at the end of the path.

All overlays support a few common configuration options:

Home > @jsplumb/common > OverlayOptions

OverlayOptions interface

Signature:

export interface OverlayOptions extends Record<string, any> 

Extends: Record<string, any>

Properties

Property	Type	Description
attributes?	Record<string, string>	(Optional)
cssClass?	string	(Optional)
events?	Record<string, (value: any, event?: any) => any>	(Optional)
id?	string	(Optional)
location?	number | number[]	(Optional)

Overlay location

A key concept with Overlays is that of their location.

For an edge, the location of an overlay refers to some point along the path inscribed by the edge. It can be specified in one of three ways:

• as a decimal in the range [0..1], which indicates some proportional amount of travel along the path inscribed by the edge. The default value of 0.5 is in this form, and it means the default location of an overlay on an edge is a point halfway along the path.
• as an integer greater than 1, which indicates some absolute number of pixels to travel along the edge from the start point
• as an integer less than zero, which indicates some absolute number of pixels to travel backwards along the edge from the end point.

For an endpoint, the same principles apply, but location is specified as an [x,y] array. For instance, this would specify an overlay that was positioned in the center of an Endpoint:

location:[ 0.5, 0.5 ]

Whereas this would specify an overlay that was positioned 5 pixels along the x axis from the top left corner:

location: [ 5, 0 ]

And this would specify an overlay that was positioned 5 pixels along the x axis from the bottom right corner:

location: [ -5, 0 ]

Default location

The default location for an overlay is halfway along the path traveled by the connector - location is 0.5. If you specify location:1, then the overlay will be at the end of the path; location:0 puts the overlay at the start.

Overlay types

The Toolkit ships with 4 overlay types, and support for creating custom overlays.

Arrow

Home > @jsplumb/common > ArrowOverlayOptions

ArrowOverlayOptions interface

Signature:

export interface ArrowOverlayOptions extends OverlayOptions 

Extends: OverlayOptions

Properties

Property	Type	Description
direction?	number	(Optional)
foldback?	number	(Optional)
length?	number	(Optional)
paintStyle?	PaintStyle	(Optional)
width?	number	(Optional)

Arrow direction

A point to note is that location:0 for arrow overlays will not reverse the direction in which the arrow is pointing. To have the arrow point backwards along the path you have to provide a value for direction:

overlays:[    
    {
        type:"Arrow",
        options:{
            width:10,
            length:15,
            location:0,
            direction:-1
        }
    }   
]

The direction:-1 here instructs the Toolkit to draw the arrow painting backwards. There are only two valid values for direction - 1 and -1. If you provide any other value - or no value - then the Toolkit will use a value of 1, meaning the arrow points forwards.

PlainArrow

This overlay is an extension of Arrow with the foldback parameter's value fixed to 1. This results in an arrow with a flat back.

Diamond

This overlay is an extension of Arrow with the foldback parameter's value fixed to 2. This results in an arrow shaped like a diamond.

Label

Home > @jsplumb/common > LabelOverlayOptions

LabelOverlayOptions interface

Signature:

export interface LabelOverlayOptions extends OverlayOptions 

Extends: OverlayOptions

Properties

Property	Type	Description
label	string | Function
labelLocationAttribute?	string	(Optional)

The label for a label overlay can be a string or a function, but in practice in the Toolkit edition you'll generally be defining labels as strings, as the values presented to the renderer are extracted from the JSON backing data for each edge