The basic model for diagram links. It inherits from joint.dia.Cell with a few additional properties and methods specific to links.

Links have two crucial attributes: source and target. They define the starting point and the end point of the link. They can be defined as an element id or as 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 }
});

These are not the only attributes that may be specified for a newly-created joint.dia.Link, however. An individual link instance may provide a value for these 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
});

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 attributes 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.

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.