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).