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.

number
If the distance is in the [0,1] range (inclusive), then the position of the label is defined as a percentage of the total length of the .connection path (the normalized length). For example, passing the number 0.5 positions the label to the middle of the .connection path.
If the distance is larger than 1 (exclusive), the label will be positioned distance pixels away from the beginning of the path along the .connection path.
If the distance is a negative number, the label will be positioned distance pixels away from the end of the path along the .connection path.
object

If position is specified as an object, it may have three properties:

distance A number specifying the distance of the label along the .connection path. Same as above.
offset

Optional. Either a number or an object with x and y properties.

number
If the offset is a positive number, displace the label perpendicularly to the right (in the direction of the .connection path) in the paper local coordinate system. (An offset of 0 is the default; it means no offset in either direction.)
If the offset is a negative number, displace the label perpendicularly to the left (in the direction of the .connection path) in the paper local coordinate system.
object
x Offset the label by x in the paper local coordinate system.
y Offset the label by y in the paper local coordinate system.
angle Optional. A number specifying the rotation of the label along the .connection path, in degrees. Angles 0-180 cause the label to rotate clockwise, angles 360-180 cause the label to rotate couterclockwise. This rotation is added on top of any rotation due to the args.keepGradient option. (Note that the args.ensureLegibility option is evaluated only after all these calculations are finished.)
args

Optional. An object with boolean options for the linkView.getLabelPosition() function.

absoluteDistance If user moves the label, record distance as an absolute number. (Relative distances are used by default.)
reverseDistance If absoluteDistance is set and user moves the label, record distance as a negative absolute number. (Positive distances are used by default.)
absoluteOffset If user moves the label, record offset as an object with absolute x and y coordinates. (Relative offsets are used by default.)
keepGradient Adjust the base rotation angle of the label (i.e. the "zero angle" before rotation due to the angle setting is applied) to match the angle of incline of the path at given distance.
ensureLegibility If keepGradient is set and the label ends up rotated so that its text is upside-down, rotate the label by additional 180 degrees so it becomes legible for the users.