JointJS supports adding labels on links. One link can have multiple labels, and each label can have different properties.

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 },
        args?: {
            absoluteDistance?: boolean,
            reverseDistance?: boolean,
            absoluteOffset?: 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.
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 used by default).
reverseDistance If absoluteDistane is set and user moves the label, record distance as a negative absolute number. (Positive distances used by default.)
absoluteOffset If user moves the label, record offset as an object with absolute x and y coordinates. (Relative offsets used by default).