JointJS supports adding labels on links. One link can have multiple labels, and each label can have different properties. For a quick introduction to link labels, see our tutorial

Properties recognized by JointJS are summarized in the following TypeScript-like schema:

{
    markup?: string | Array<{
        tagName: SVGElement,
        selector?: string
    }>,
    attrs?: {
        [key: selector]: {
            [key: SVG attribute | JointJS attribute]: any
        } | null
    },
    position?: number | {
        distance: number,
        offset?: number | { x: number, y: number },
        angle?: number,
        args?: {
            absoluteDistance?: boolean,
            reverseDistance?: boolean,
            absoluteOffset?: boolean,
            keepGradient?: boolean,
            ensureLegibility?: boolean
        }
    }
}

Markup

The markup property specifies the markup of the label. It can be provided either as a parsable SVG (e.g. '<rect /><text />'), or as a JSON array (e.g.[{ tagName: 'rect' }, { tagName: 'text' }]). The JSON allows the user to specify custom selectors for the SVGElements; these can then be used for targeting elements from within the attrs property.

If markup is not provided on the label, markup is taken from the Link type's defaultLabel.markup property. A custom Link type can be created by the user, providing a defaultLabel (see the Link documentation for more information). However, if the used link type does not provide defaultLabel.markup (this includes joint.dia.Link and joint.shapes.standard.Link), the builtin default Link markup is used, which defines markup as a JSON array with a 'body' (a <rect> SVGElement) under a 'label' (a <text> SVGElement).

Styling

The attrs property is an object where the keys are CSS selectors (referring to custom selectors or SVGElements specified in markup, e.g. body in the above example). They are expected to contain objects that specify native SVG and/or JointJS special attributes (e.g. fill), alongside the value to be assigned (e.g. 'white').

If the Link type provides defaultLabel.attrs, these attrs are merged with label.attrs. This allows you to reference selectors from defaultLabel.markup in label.attrs and, for example, simply add an attribute (attrs: { body: { stroke: 'black' } }).

If the builtin default markup is used (i.e. no custom label.markup was provided, and no defaultLabel.markup), several builtin default attrs are applied for reasons of backwards compatibility. These are merged with defaultLabel.attrs (if present on the Link prototype) and then label.attrs (if provided). See Link documentation for more information.

Position

Finally, the position property specifies the position of the label, relative to the SVG path of the link. It may be defined as a number or as an object with distance and optionally offset and args properties. If no position is provided, the builtin default ({ distance: 0.5 }) is used to maintain backwards compatibility.