The basic model for diagram links. It inherits from joint.dia.Cell with a few additional properties and methods specific to links. For a quick introduction to elements, see our tutorial.

Links' properties may be split into several groups according to their function:

Geometry

Links have two crucial attributes: source and target. They define the starting point and the end point of the link. They can be defined with a Cell id (optionally, with additional subelement/magnet/port reference) or with a Point:

var link1 = new joint.dia.Link({
    source: { id: sourceId },
    target: { id: targetId, port: portId }
});

var link2 = new joint.dia.Link({
    source: { id: sourceId },
    target: { x: 100, y: 100 }
});

The source and target properties accept additional modifier properties that modify the actual position of the link end: anchor/linkAnchor, and connectionPoint.

Additionally, the path of the link is determined by its vertices, and the applied router and connector. All these attributes are described in more detail in link geometry documentation.

Presentation

Each joint.dia.Link defines its own SVG markup which is then used by joint.dia.LinkView to render the link to the paper. For instance, the joint.shapes.standard.Link (which inherits from joint.dia.Link) defines its markup using the JSON array notation as follows:

markup: [{
    tagName: 'path',
    selector: 'wrapper',
    attributes: {
        'fill': 'none',
        'cursor': 'pointer',
        'stroke': 'transparent',
        'stroke-linecap': 'round'
    }
}, {
    tagName: 'path',
    selector: 'line',
    attributes: {
        'fill': 'none',
        'pointer-events': 'none'
    }
}]

As we can see, the joint.shapes.standard.Link shape consists of two subelements: one SVGPathElement named 'wrapper' and one SVGPathElement named 'line'. The attrs object refers to the subelements' names (selectors) to provide SVG attributes to these constituent SVGElements.

Direct use of joint.dia.Link is deprecated. Use links from standard namespace.

The joint.dia.Link markup looks like:

<path class="connection"/>
<path class="marker-source"/>
<path class="marker-target"/>
<path class="connection-wrap"/>
<g class="labels" />
<g class="marker-vertices"/>
<g class="marker-arrowheads"/>
<g class="link-tools" />

As you can see, the link consists of a couple of SVG path elements and couple of SVG group elements:

link.attr({
        '.connection': { stroke: 'blue' },
        '.marker-source': { fill: 'red', d: 'M 10 0 L 0 5 L 10 10 z' },
        '.marker-target': { fill: 'yellow', d: 'M 10 0 L 0 5 L 10 10 z' }
    });

The markup attribute is not the only presentation attribute that may be specified for a joint.dia.Link. However, all the following Link properties are deprecated and included only for backwards compatibility. Use link tools instead:

Styling

The keys of the attrs object are selectors that match subelements defined in the link's markup. The values of this object are SVG attributes that will be set on the selected subelements. One can find the full list of SVG attributes and their descriptions online, e.g. on MDN.

For example, in order to set a red stroke color on a subelement called 'line', the attrs object would contain:

line: { stroke: 'red' }

If you simply need to change a value of an attribute, it is not recommended to modify the attrs object directly. Instead, use the link.attr() method.

We can use the joint.shapes.standard.Link (which inherits from joint.dia.Link) as an example. The attrs object in its definition is provided below:

attrs: {
    line: {
        connection: true,
        stroke: '#333333',
        strokeWidth: 2,
        strokeLinejoin: 'round',
        targetMarker: {
            'type': 'path',
            'd': 'M 10 -5 0 0 10 5 z'
        }
    },
    wrapper: {
        connection: true,
        strokeWidth: 10,
        strokeLinejoin: 'round'
    }
}

Notice that the object makes use of special JointJS attributes (e.g. connection, targetMarker) on top of standard SVG attributes (e.g. stroke, strokeWidth). All of these special attributes are listed in the attributes section of this documentation. You should also refer to our tutorial on special attributes.

In the context of links, the most important special attribute is connection. It specifies that the SVGPathElement(s) in question should follow the path of the Link's model, as provided by the interplay of link geometry methods.

Z

The z property specifies the stack order of the element in the SVG DOM. An element with a higher z value will be rendered in front of an element with a lower z value. (This also applies to Elements.)

Labels

You may provide an array of labels to the link through the labels attribute. Each can have its own markup, position, and attrs. See the link labels documentation. You should also refer to our tutorial on link labels.

Custom Attributes

It is also possible to pass custom attributes to the link. These may be useful to identify an individual link model for the purposes of linkView interaction (see LinkView documentation for more information). For example, to only enable custom contextmenu interaction for link1 but not link2:

var CustomLinkView = joint.dia.LinkView.extend({
    contextmenu: function(evt, x, y) {
        if (this.model.get('customLinkInteractions')) {
            // only links with `customLinkInteractions: true`
            this.addLabel(x, y);
        }
    }
});

var paper = new joint.dia.Paper({
    //...
    linkView: CustomLinkView,
    interactive: function(cellView) {
        if (cellView.model.get('customLinkInteractions')) {
            // only links with `customLinkInteractions: true`
            return { vertexAdd: false };
        }
        return true; // otherwise
    }
});

var link1 = new joint.dia.Link({
    //...
    customLinkInteractions: true // right-click adds a label
});

var link2 = new joint.dia.Link({
    //...
    customLinkInteractions: false // or omit completely
});

Events

Links trigger several special events, detailed in the link events documentation.

It is possible to extend the joint.dia.Link class to create a custom link. A custom link may override Link properties to assign its own defaults. These values override builtin defaults, if provided, and are applied to all instances of the new Link type, unless an individual instance overrides them with its own values. The following Link properties are applicable in this context:

The values of these defaults may be important; the linkView.addLabel() shortcut function is only capable of adding default labels to the link.

Creating custom links is explained in more detail in our tutorial.

Example:

var CustomLink = joint.dia.Link.define('examples.CustomLink', {
    defaultLabel: {
        markup: [
            {
                tagName: 'circle',
                selector: 'body'
            }, {
                tagName: 'text',
                selector: 'label'
            }
        ],
        attrs: {
            label: {
                text: '%', // default label text
                fill: '#ff0000', // default text color
                fontSize: 14,
                textAnchor: 'middle',
                yAlignment: 'middle',
                pointerEvents: 'none'
            },
            body: {
                ref: 'label',
                fill: '#ffffff',
                stroke: '#000000',
                strokeWidth: 1,
                refR: 1,
                refCx: 0,
                refCy: 0
            }
        },
        position: {
            distance: 0.5, // place label at midpoint by default
            offset: {
                y: -20 // offset label by 20px upwards by default
            },
            args: {
                absoluteOffset: true // keep offset absolute when moving by default
            }
        }
    }
});

var link = new CustomLink({
    //...
});

Builtin Default Attributes

To ensure backwards compatibility, the joint.dia.Link class comes with a private builtin defaultLabel attribute. It is reproduced here for reference:

defaultLabel: {
    // builtin default markup:
    // used if neither defaultLabel.markup
    // nor label.markup is set
    markup: [
        {
            tagName: 'rect',
            selector: 'rect'
        }, {
            tagName: 'text',
            selector: 'text'
        }
    ],
    // builtin default attributes:
    // applied only if builtin default markup is used
    attrs: {
        text: {
            fill: '#000000',
            fontSize: 14,
            textAnchor: 'middle',
            yAlignment: 'middle',
            pointerEvents: 'none'
        },
        rect: {
            ref: 'text',
            fill: '#ffffff',
            rx: 3,
            ry: 3,
            refWidth: 1,
            refHeight: 1,
            refX: 0,
            refY: 0
        }
    },
    // builtin default position:
    // used if neither defaultLabel.position
    // nor label.position is set
    position: {
        distance: 0.5
    }
}

If custom position object is not provided (neither as a type default nor as an instance value), builtin default label position is applied instead ({ distance: 0.5 }).

Furthermore, if custom markup is not provided (neither as a type default nor as an instance value), builtin default label markup is applied, alongside the builtin default label attrs object. However, it is very highly recommended that you provide both your own markup and your own attrs - unless you want to use the builtin default precisely as-is.