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.