Link Labels

This is the sixth article of the intermediate section of the JointJS tutorial. Go back to custom links. Alternatively, you can return to index of all articles.

The basic tutorial series offered an introduction into link labels. This section explains everything you need to know to make full use of the powerful label system.

JointJS offers a full suite of methods for working with link labels:

Builtin Default Label

A simple label definition (including markup and attrs) is built into the joint.dia.Link class, from which all subtypes, including joint.shapes.standard.Link, inherit it. The builtin default label has two tags: text (the <text> SVGElement of the label), and rect (the <rect> SVGElement for label background). The builtin default attributes specify a simple vertical-centered text on a white rounded rectangle. Thus, adding a label can be as simple as passing a value for the text/text attribute:

link.appendLabel({
    attrs: {
        text: {
            text: 'Hello, World!'
        }
    }
});

JointJS source code: links-label-builtin.js

The full builtin default label definition can be found in the documentation.

Label Position

Labels are positioned at the center point of the link (distance of 0.5) by default. Three kinds of label.position.distance values are recognized for setting custom position. A value between 0 and 1 causes the label to be positioned relatively to link length. Positive values signify absolute position in local SVG units away from start point. Finally, negative values mean absolute position away from end point. An animated example is presented below. (Link labels can also be emulated with link subelements and special attributes; this technique is explained elsewhere in the tutorial.)

link.appendLabel({
    attrs: {
        text: {
            text: '0.25'
        }
    },
    position: {
        distance: 0.25
    }
});

link.appendLabel({
    attrs: {
        text: {
            text: '150'
        }
    },
    position: {
        distance: 150
    }
});

link.appendLabel({
    attrs: {
        text: {
            text: '-100'
        }
    },
    position: {
        distance: -100
    }
});

JointJS source code: link-labels-distance.js

Label Offset

It is also possible to set label offsets. This is done with the label.position.offset property. With a positive number, the label is offset relatively and to the right of the link; a negative number causes the label to be offset to the left. An object with x and y coordinates offsets the label absolutely by that amount in the two dimensions. The following example illustrates these three options. The red asterisk marks the reference point of all labels on the link. (Link labels can also be emulated with link subelements and special attributes; this technique is explained elsewhere in the tutorial.)

link.appendLabel({
    attrs: {
        text: {
            text: 'offset: 40'
        }
    },
    position: {
        distance: 0.66,
        offset: 40
    }
});

link.appendLabel({
    attrs: {
        text: {
            text: 'offset: -40'
        }
    },
    position: {
        distance: 0.66,
        offset: -40
    }
});

link.appendLabel({
    attrs: {
        text: {
            text: 'offset: -40,80'
        }
    },
    position: {
        distance: 0.66,
        offset: {
            x: -40,
            y: 80
        }
    }
});

JointJS source code: link-labels-offset.js

By default, labels' anchor point is centered horizontally and vertically, as it was in this example. This can be changed by the textAnchor and textVerticalAnchor attributes, respectively.

Label Styling

Of course, it is also possible to change the appearance of your labels. Simply specify custom markup in JSON format and pass some attrs. As a bonus, you can define custom selectors to identify individual components of your label. Let's define a complex circular label that shows what JointJS can do:

link.appendLabel({
    markup: [
        {
            tagName: 'circle',
            selector: 'body'
        }, {
            tagName: 'text',
            selector: 'label'
        }, {
            tagName: 'circle',
            selector: 'asteriskBody'
        }, {
            tagName: 'text',
            selector: 'asterisk'
        }
    ],
    attrs: {
        label: {
            text: '½',
            fill: '#000000',
            fontSize: 14,
            textAnchor: 'middle',
            yAlignment: 'middle',
            pointerEvents: 'none'
        },
        body: {
            ref: 'label',
            fill: '#ffffff',
            stroke: '#000000',
            strokeWidth: 1,
            refR: 1,
            refCx: 0,
            refCy: 0
        },
        asterisk: {
            ref: 'label',
            text: '*',
            fill: '#ff0000',
            fontSize: 8,
            textAnchor: 'middle',
            yAlignment: 'middle',
            pointerEvents: 'none',
            refX: 16.5,
            refY: -2
        },
        asteriskBody: {
            ref: 'asterisk',
            fill: '#ffffff',
            stroke: '#000000',
            strokeWidth: 1,
            refR: 1,
            refCx: '50%',
            refCy: '50%',
            refX: 0,
            refY: 0
        }
    }
});

JointJS source code: link-labels-styling.js

The ref attributes are an example of JointJS special attributes. These are discussed in detail elsewhere in the tutorial.

In the next section of the intermediate tutorial, we will learn about link tools.