Item Format

KeyLines uses JavaScript objects for defining visual appearances.

ChartData

The chart object lets you load JSON data into the chart. In this example, only the type, id, id1, id2 and subject properties are required:

let data = {
  type: 'LinkChart',           // this must be exactly this string
  items: [
    { 
      id: 'node1',             // the identity of the node
      type: 'node',            // the type of the item: must be 'node'
      c: 'blue'                // the fill colour (optional)
    },
    { 
      id: 'node2',             // the identity of the node
      type: 'node',            // the type of the item: must be 'node'
      c: 'blue'                // the fill colour (optional)
    },
    {
      id: 'link1-2',           // the identity of the link
      id1: 'node1',            // the identity of the node at one end
      id2: 'node2',            // the identity of the node at the other end
      type: 'link',            // the type of the item: must be 'link'
      c: 'rgb(216, 30, 91)'    // the link colour (optional)
    },
    {
      id: 'annotation1',       // the identity of the annotation
      subject: 'node1',     // the identity of the annotated item
      type: 'annotation',      // the type of the item: must be 'annotation'
      t: { t: 'Annotation Label' },  // the annotation text (optional)
    }
  ]
};

items

required

(Node | Link | Annotation)[]

An array of nodes, links and annotations.

type

required

'LinkChart'

A KeyLines Chart type - must be 'LinkChart'.

Node

Nodes are the basic objects that you use to build a graph.

By default, nodes don't have a defined body unless their background is specified. To create a defined body, set a background fill colour (c), a font icon (fi), or a background image (u).

let data = {
  type: 'LinkChart',
  items: [
    {
      id: 'node1',
      type: 'node',
      c: '#43976C',
    },
  ],
};

Either font icons or images can also be used alongside a background fill colour as a top layer over the coloured node.

You can set the properties of nodes using setProperties.

b

string(Colour)default: No border

The border colour.

bg

booleandefault: false

Whether the node is displayed in the background.

borderRadius

number | string | number[] | objectdefault: '0 0 0 0'

The radius of the corners. Accepts a single number setting equal radius to all corners, a string of numbers separated by spaces (ordered top left, top right, bottom right, bottom left), an array of numbers separated by commas, or an object setting values for individual properties such as topLeft or bottomRight.

bs

"solid" | "dashed"default: 'solid'

The style of the border line.

bu

Deprecated

Bubble

An object describing the bubble shown on the node. Deprecated as we recommend using annotations instead.

bw

numberdefault: 4

The width of the node's border.

c

string(Colour)

The node background fill colour. Can also be set to 'rgba(0,0,0,0)' to create a fully transparent node with a defined body.

ci

booleandefault: false

Whether the image should be a cutout circle from the original image. Does not apply to font icons.

d

object

The d parameter stands for data. Use this to store custom data on the node.

donut

Donut

An object describing the donut border shown on the node. Only applies to circle nodes - nodes with sh (shape) property set to 'circle'. If both donut and b are set then donut takes precedence.

e

numberdefault: 1

The enlargement factor for the node. Does not apply to nodes with w and h specified.

fb

booleandefault: false

Whether the label should be displayed in bold font.

fbc

string(Colour)default: white with alpha channel

The background colour of the font.

fc

string(Colour)default: black

The colour of the label font.

ff

string

The font family to use for the label. The default is inherited from the fontFamily setting of chart.options().

fi

null | FontIcon

The font icon used on the node.

fs

numberdefault: 14

The font size (px) of the node label. By default the font size will scale with the node's e property.

g

Glyph[]

An array of objects describing the glyphs shown on the node.

h

number | "auto"

When specified with w: the height of the node in world coordinates. Set to 'auto' to fit the node height to any number or length of labels inside.

ha0-9

Halo

The halo shown on the node. There are ten halo properties, ha0, ha1, ha2, etc., up to ha9.

hi

booleandefault: false

Whether the node is hidden. See also show and hide.

id

required

string

The identity of the node. Must be unique across all items in the chart. Must not start with an underscore or end with a '\' character.

minHeight

numberdefault: 54

The minimum height of a node.

minWidth

numberdefault: 54

The minimum width of a node.

oc

OpenStyleOptions

The style of the open combo.

b

string(Colour)default: 'grey'

The border colour.

borderRadius

number | string | number[] | objectdefault: '0 0 0 0'

The corner radius. Accepts a number to set radius to all corners, a string of space-separated numbers ( top left, top right, bottom right, bottom left), an array of comma-separated numbers, or an object setting values for properties such as topLeft or bottomRight.

bs

"solid" | "dashed"default: 'solid'

The style of the border line.

bw

numberdefault: 1

The border width.

c

stringdefault: 'light grey'

The background colour of the open combo.

g

Beta

Glyph[]

An array of objects describing the glyphs shown on the open combo.

h

number

The height of the open rectangular combo. Set to fit all content when the combo is created.

re

booleandefault: false

Whether resize handles are shown on open combos.

t

string | NodeLabel | NodeLabel[]

string - A simple text string label.
Beta NodeLabel - A single label object that can contain label styling properties.
Beta NodeLabel[] - An array of objects to add multiple labels where each label can be styled individually.

For more details about label styling see the Advanced combo styling documentation.

w

number

The width of the open combo. This is automatically set to fit all content when the combo is created. Set this option after the combo has been created.

parentId

null | string

The id of the parent node, if it is a member of a combo. Can be set explicitly during combo creation, but after that you should use chart.combo().transfer() to change it.

pos

Location

An object describing the position of the node on the Leaflet map.

lat

required

number

The latitude in degrees that this node is positioned at on a Leaflet map. Should be in the range -90 to 90, but larger values will be rounded to ±90 respectively.

lng

required

number

The longitude in degrees that this node is positioned at on a Leaflet map. Should be in the range -180 to 180 but larger values will wrap at the antimeridian.

re

Deprecated

booleandefault: false

Whether resize handles are shown on a legacy shape node. Shape nodes are drawn behind other chart items and are only available when legacyShapeNodeBehaviour is enabled.

sh

"circle" | "box"default: 'circle'

The node's shape. Set to 'box', without setting h and w, to create a scalable square node. Defaults to 'box' for nodes with h and w specified.

t

string | NodeLabel | NodeLabel[]default: No label

string - A simple text string label.
Beta NodeLabel - A single label object that can contain label styling properties.
Beta NodeLabel[] - An array of objects to add multiple labels where each label can be styled individually.

For more details about label styling see the Advanced label styling documentation.

tc

Deprecated

booleandefault: true for nodes / false for nodes with images

If true, labels are shown in the centre of the node. If false, labels are shown at the bottom of the node. Deprecated as we recommend using the position option instead.

type

required

'node'

The type of the item.

u

string

The URL of the image used on the node. To prevent non-square images from being distorted, set the node dimensions in w and h node properties in proportion to the aspect ratio of the image.

w

number | "auto"

When specified with h: the width of the node in world coordinates. Set to 'auto' to fit the node width to any number or length of labels inside.

x

numberdefault: 0

The node position along the X-axis, in world coordinates.

y

numberdefault: 0

The node position along the Y-axis, in world coordinates.

Link

In KeyLines, connections between nodes are called links. Links represent connections in your data and are used to show network structure. You can set the properties of links using setProperties.

a1

booleandefault: false

Whether to show an arrow at the id1 end.

a2

booleandefault: false

Whether to show an arrow at the id2 end.

b1

numberdefault: 0

The distance to back-off from end id1 as a ratio of the total length of the link line. Value in the range 0 to 1.

b2

numberdefault: 0

The distance to back-off from end id2 as a ratio of the total length of the link line. Value in the range 0 to 1.

bg

booleandefault: false

Whether the link is displayed in the background.

border

object

The border around the link label. If set for multiline labels, merges all labels into a single label container.

colour

string(Colour)default: No border

The border colour.

radius

number | string | number[] | objectdefault: '0 0 0 0'

The radius of the label corners. Accepts a single number setting equal radius to all corners, a string of numbers separated by spaces (ordered top left, top right, bottom right, bottom left), an array of numbers separated by commas, or an object setting values for individual properties such as topLeft or bottomRight.

width

numberdefault: 4

The border width. Requires colour to also be set.

bu

Deprecated

Bubble

An object describing the bubble shown on the link. Deprecated as we recommend using annotations instead.

c

string(Colour)default: 'grey'

The colour of the link line.

c2

string(Colour)

If specified, the link will have a colour gradient, with colour c at the id1 end and colour c2 at the id2 end. The transition setting of linkStyle controls the gradient's appearance.

d

object

The d parameter stands for data. Use this to store custom data on the link.

fb

booleandefault: false

Whether the label should be displayed in bold font.

fbc

string(Colour)default: white with alpha channel

The background colour of the font.

fc

string(Colour)default: 'black'

The colour for the label font.

ff

string

The font family to use for the label. The default is inherited from the fontFamily setting of chart.options().

flow

boolean | FlowOptionsdefault: false

Options to customise the flow animation on the link. Set to true to enable flow with a default velocity of 2. Note that flowing links are always shown as dashed (overriding the ls property).

velocity

numberdefault: 2

The velocity of the flow on the link. Positive values flow from id1 to id2, and negative from id2 to id1. Must be in the range -10 to 10.

fs

numberdefault: 14

The font size (px) of the link label.

g

Glyph[]

An array of objects setting the glyphs in the link centre next to the label. To add a glyph at a link end, set the g property within t1 or t2.

hi

booleandefault: false

Whether the link is hidden. See also show and hide.

id

required

string

The identity of the link. This must be unique across all items in the chart. It must not end with a '\' character.

id1

required

string

The identity of the node at one end of the link.

id2

required

string

The identity of the node at the other end of the link. This may be the same as id1 to create a "self link" if the selfLinks chart option is enabled.

linkShape

Beta

LinkShapeOptions

The shape and orientation of the path taken by the link.

direction

"horizontal" | "vertical"

If name is set to 'angled' or 'curved', the direction in which the link attaches to its nodes.

name

required

"direct" | "curved" | "angled"

The shape of the path taken by this link:

'direct' - either straight or, when offset, following an arc.
'curved' - a curved path.
'angled' - a straight, branching path: useful for hierarchical data sets. Currently in beta.

ls

"solid" | "dashed" | "dotted"default: 'solid'

The style of the link line.

off

numberdefault: 0

Overrides automatic calculation of link offsets, so can be used to force direct links to follow an arc. Increasing off increases the distance between the midpoint of the link and the straight line joining its ends. If off is set for any link in a set of links between two nodes, then it defaults to 0 for any other links in that set.

Note: When chart.layout runs with default settings, off is overriden because straighten is true. To prevent this, and preserve specified offsets, set straighten to false.

Similarly, when chart.combo().arrange() runs with default settings, off is overriden because straighten is true. To prevent this, and preserve specified offsets, set it to false.

For self links, this option specifies how far the link is offset from its default position close to the node.

padding

number | string | number[] | objectdefault: '2 2 0 2'

The distance between the link label text and the label edge. Borders are excluded. If used on multiline labels with border set, applies to the whole label container.

parentId

null | string

The id of the parent combo or link (if it is a member of a combo). Note that parentIds for links are calculated automatically and cannot be set.

priority

Beta

0 | 1default: 0

The priority of the link; see Prioritising links.

t

string

The label positioned at the centre of the link. For multiline labels, use '\n' or '\r' to force a line break.

t1

string | LinkEndLabel

The link label positioned at the id1 end. For multiline labels, use '\n' or '\r' to force a line break. String values inherit styling from the label at the link's centre.

border

LinkLabelBorder

The border around the link label. Note that if t1 / t2 inherit the styling in the border object, any unspecified values will be set to defaults.

colour

string(Colour)default: No border

The border colour.

radius

number | string | number[] | objectdefault: '0 0 0 0'

width

numberdefault: 4

The border width. Requires colour to also be set.

fb

boolean

Whether the label should be displayed in bold font. The default is inherited from the link's fb setting.

fbc

string(Colour)

The background colour of the font. The default is inherited from the label at the centre of the link.

fc

string(Colour)

The colour for the label font. The default is inherited from the label at the centre of the link.

ff

string

The font family to use for the label. The default is inherited from the label at the centre of the link.

fs

number

The font size (px) of the link label. The default is inherited from the label at the centre of the link.

g

Glyph[]

An array of objects describing the glyphs shown in the centre of link next to the label.

padding

number | string | number[] | objectdefault: '2 2 0 2'

The distance between the link label text and the label edge. Borders are excluded. If used on multiline labels with border set, applies to the whole label container.

t

string

The link label. For multiline labels, use '\n' or '\r' to force a line break.

t2

string | LinkEndLabel

The link label positioned at the id2 end. For multiline labels, use '\n' or '\r' to force a line break. String values inherit styling from the label at the link's centre.

border

LinkLabelBorder

The border around the link label. Note that if t1 / t2 inherit the styling in the border object, any unspecified values will be set to defaults.

colour

string(Colour)default: No border

The border colour.

radius

number | string | number[] | objectdefault: '0 0 0 0'

width

numberdefault: 4

The border width. Requires colour to also be set.

fb

boolean

Whether the label should be displayed in bold font. The default is inherited from the link's fb setting.

fbc

string(Colour)

The background colour of the font. The default is inherited from the label at the centre of the link.

fc

string(Colour)

The colour for the label font. The default is inherited from the label at the centre of the link.

ff

string

The font family to use for the label. The default is inherited from the label at the centre of the link.

fs

number

The font size (px) of the link label. The default is inherited from the label at the centre of the link.

g

Glyph[]

An array of objects describing the glyphs shown in the centre of link next to the label.

padding

number | string | number[] | objectdefault: '2 2 0 2'

The distance between the link label text and the label edge. Borders are excluded. If used on multiline labels with border set, applies to the whole label container.

t

string

The link label. For multiline labels, use '\n' or '\r' to force a line break.

type

required

'link'

The type of the item.

w

numberdefault: 1

The width of the link line. Also affects the size of arrowheads if present.

Annotation

Beta

Annotations are notes that can annotate the chart or the items in the chart. You can annotate nodes, links, open and closed combos, and create free-standing annotations without any subjects.

See also the Annotations documentation for more information.

Annotations are added as special type of chart item in the items array. The subject array is set differently for annotations with and without subjects:

let data = {
  type: 'LinkChart',
  items: [
    {
      id: 'annotation1',
      type: 'annotation',
      subject: 'node1',                                // node1 is annotation subject
      t: { t: 'This is an annotation of node 1.' },
      connectorStyle: { container: 'rectangle' }
    },
    {
      id: 'annotation2',
      type: 'annotation',
      t: { t: 'This is an annotation without subject.' },
      subject: [],                                     // an empty array indicates no subjects
      position: { x: 350, y: -50 },   // no-subject annotation requires coordinate positioning
    },
    {
      id: 'node1',
      type: 'node',
      c: 'rgb(45,105,160)',
    },
  ]
};

Annotations are drawn in a separate layer on top of the chart and they do not scale during zooming.

There are two ways of positioning annotations:

Subject-relative - places annotations relative to their subjects. When a layout is run or when the subjects move, annotations remain relative to their subjects.
World-coordinate - places annotations on the chart using coordinates. They are fixed during chart changes such as zooming, panning, items moving or subject changing. Available for annotations with or without subjects.

Annotations with subjects are displayed if at least one of the annotated items is visible in the chart, or if none of the subjects are visible but the annotation uses world coordinates for positioning.

Annotations without subjects must use world coordinates for positioning and require the subject array to be set to an empty array.

Notes:

Annotations cannot be selected or backgrounded.
Annotations are not shown on a Leaflet map.
Annotations for time bar are not supported.

b

stringdefault: 'rgb(230, 230, 230)'

The border colour.

borderRadius

number | string | number[] | objectdefault: '3, 3, 3, 3'

The corner radius of the annotation. Accepts a single number setting equal radius to all corners, a string of numbers separated by spaces (ordered top left, top right, bottom right, bottom left), an array of numbers separated by commas, or an object setting values for individual properties such as topLeft or bottomRight.

bs

"solid" | "dashed"default: 'solid'

The style of the border line.

bw

numberdefault: 1

The width of the border.

c

stringdefault: 'white'

The fill colour.

connectorStyle

ConnectorStyle

The style of the connector between the annotation and the annotated subject(s). The connector has three parts:

A line towards the subject, or multiple lines if there are multiple subjects.
The decoration at the subject end of the line(s). Can be set in the subjectEnd option for any annotations.
A container around the subject(s). Can be set in the container option for node and combo annotations.

c

stringdefault: 'black'

The colour of the connector.

container

"none" | "circle" | "rectangle"default: 'none'

Whether there should be a container around the subject(s):

'none' - No container is drawn. When annotating links, this is the only option available.
'circle' - Draws a circle around the subject node(s) or combo(s).
'rectangle' - Draws a rectangle around the subject node(s) or combo(s).

ls

"solid" | "dashed"default: 'solid'

The style of the connector line(s) and subject container(s).

subjectEnd

"none" | "dot" | "arrow"default: 'dot'

The decoration shown at the subject end of the connector line.

w

numberdefault: 1

The width of the connector line(s) and the container lines. Also affects the size of subjectEnd. Set to 0 to hide the connector and create an annotation that isn't visibly connected to subjects but remains in a relative position to them.

d

object

The d parameter stands for data. Use this to store custom data on the annotation.

g

Glyph[]

An array of objects describing the glyphs shown on the annotation.

h

number | "auto"default: 'auto'

The annotation's height in view coordinates. When set to 'auto', the annotation automatically sizes to fit any content inside. When setting exact dimensions for annotations, both h and w need to be set.

hi

booleandefault: false

Whether the annotation is hidden.

id

required

string

The identity of the annotation. Must be unique across all items in the chart. Must not start with an underscore or end with a '\' character.

minHeight

numberdefault: 10

The minimum height of an annotation.

minWidth

numberdefault: 56

The minimum width of an annotation.

position

AnnotationRelativeViewPosition | Coordinates

An object to set the position of the annotation. There are two positioning methods, each using some of the options below:

Subject-relative positioning using the angle and distance properties
World-coordinate positioning using the x and y properties

angle

string | numberdefault: 0

In subject-relative positioning, the angle relative to annotation subject(s). Use a compass point value ( 'n', 'ne' etc.) or integer degrees clockwise from the top (in the range 0-359).

distance

numberdefault: 20

In subject-relative positioning, the distance between the annotation and its subject(s) in view coordinates.

x

required

number

In world-coordinate positioning, the horizontal coordinate.

y

required

number

In world-coordinate positioning, the vertical coordinate.

subject

required

string | string[]

The id(s) of the item(s) to which the annotation refers. Set to an empty array for annotation without subjects.

t

AnnotationLabel | AnnotationLabel[]default: No label

The annotation label.

type

required

"annotation"

The type of the item.

w

number | "auto"default: 'auto'

The annotation's width in view coordinates. When set to 'auto', the annotation automatically sizes to fit any content inside. When setting exact dimensions for annotations, both h and w need to be set.

NodeLabel

Beta

Labels show information on nodes. They can contain text, font icons or images.

A basic label is a text string set directly in the t property such as t: 'label 1', but the t property also accepts an object that lets you further customise the label styling:

t:
  {
    t: 'Label',
    b: 'rgb(45,105,160)'
  }

or an array of objects that lets you add multiple labels and customise styling for each label:

let data = {
  type: 'LinkChart',
  items: [{
    id: 'node1',
    type: 'node',
    c: 'rgb(45,105,160)',
    t: [
        {
          fi: { t: 'fas fa-exclamation-circle' },
          fc: 'rgb(216, 30, 91)',
          fbc: 'transparent',
          position: 'ne',
        },
        {
          t: 'node label',
          borderRadius: 5,
          position: 's',
          fbc: 'rgb(122,193,226)',
        },
        {
          u: '/images/icons/pearlgirl.jpg',
          position: { horizontal: 'centre'},
        },
      ],
    }]};

For more details, see Advanced label styling.

Labels on open and closed combos

Closed combos accept the same node label API as nodes and have the same defaults.

Open combos accept the same node label API, but their default label position is outside and below the combo to avoid overlapping the combo content. For more details, see Advanced combo styling.

b

string(Colour)default: No border

The colour of the label container's border.

borderRadius

number | string | number[] | objectdefault: '0 0 0 0'

The radius of the label's corners. Set this as a single value to be applied to all corners, or set individual corners as a string of space-separated numbers ( top left, top right, bottom right, bottom left), an array of comma-separated numbers, or an object setting values for properties such as topLeft or bottomRight.

bw

numberdefault: 4

The width of the label's border.

fb

booleandefault: parent node fb / false

Whether the label content should be in bold font.

fbc

string(Colour)default: parent node fbc / white with alpha channel

The colour of the label's background. The default is inherited from the parent nodes's fbc, if it's set. Ignored if u is set.

fc

string(Colour)default: parent node fc / black

The font colour of the label content. The default is inherited from the parent nodes's fc, if it's set.

ff

string

The font family to use for the label content. The default is inherited from the parent node ff if set, or from the fontFamily setting of chart.options().

fi

FontIcon

The font icon to use as the label content. To set its position and offset, use position and margin, and scale it using fs. If both fi and t are specified, only fi is shown. fi is ignored if u is also specified.

fs

number | "auto"default: parent node fs / 14

The font size. Set to 'auto' to size the font automatically depending on the node/combo size. Note that if both w and h node dimensions are set to 'auto', setting the font size to 'auto' will revert to the node's font size instead of trying to fit to the available space.

margin

number | string | number[] | objectdefault: '0 0 0 0'

The distance between the label and another label, or the label and its parent node/combo. Calculated outside of label or node/combo borders.

See also Margin, padding and borders for details and accepted value formats.

maxHeight

numberdefault: 54 for images

The height of the label container:

For text and font icon labels: the maximum height. Use this to limit the text height when fs is set to 'auto'.
For image labels: the image height if maxWidth also set.

maxWidth

numberdefault: 54 for images

The width of the label container:

For text and font icon labels: the maximum width. Use it to reduce the text width before a line break when textWrap is set to 'normal', or set the maximum text width when fs is set to 'auto'.
For image labels: the image width if maxHeight also set.

minHeight

number | "stretch"

The minimum height of the label container. Will always fit the content. Set to 'stretch' to draw the label across the whole node/combo height. Ignored if u is set.

minWidth

number | "stretch"

The minimum width of the label container. Will always fit the content. Set to 'stretch' to draw the label across the whole node/combo width. Set minWidth when textWrap is set to 'normal' to increase the minimum text width before a line break. Ignored if u is set.

padding

number | string | number[] | objectdefault: '2 2 0 2'

The distance between the label content and the label container. Borders are excluded.

See also Margin, padding and borders for details and accepted value formats.

position

string | object

Sets the label position in relation to the node.

The compass point values ( 'n', 'ne' etc.) place labels outside the node/combo.

An object with horizontal and/or vertical properties places labels inside the node/combo.

Default position for nodes and closed combos is in the middle and centre of the node.

Default position for open combos is outside and below the combo.

If there are multiple labels with completely or partially overlapping positions, the label which was processed later will be drawn over the label which was processed earlier.

See also Label positioning and Advanced combo styling for details.

horizontal

"left" | "right" | "centre" | number

The horizontal position. The number in world coordinates sets the horizontal position of the label's top left corner in relation to the top left corner of the node/combo.

vertical

The vertical position. The number in world coordinates sets the vertical position of the label's top left corner in relation to the top left corner of the node/combo. The 'initial' value puts the label in the default position.

The 'inherit' value puts the label on the same line as the previous label:

t: [
  // label 1 has no vertical position, set label 2 to 'inherit' to place it inline
  { t: 'label 1' },
  { t: 'label 2', position: { vertical: 'inherit' } },
]

Similarly, setting two labels to the same vertical position will also put them on the same line:

t: [
  // set label 2 to the same vertical position as label 1 to place it inline
  { t: 'label 1', position: { vertical: 'bottom' } },
  { t: 'label 2', position: { vertical: 'bottom' } },
]

t

string

The text to use as the label content. t is ignored if fi or u is also specified.

textAlignment

object

The alignment of text or font icons inside the label.

horizontal

"left" | "right" | "centre"default: 'centre'

The horizontal alignment.

vertical

"top" | "bottom" | "middle"default: 'middle'

The vertical alignment.

textWrap

"initial" | "normal"default: 'initial'

Text wrapping inside the label. By default, no text wrapping is used. If set to 'normal', the label content is wrapped on whitespaces created by the space bar. To control line breaks, use minWidth / maxWidth, or the '\n' or '\r' characters. To set a fixed width for a wrapped label, set both minWidth and maxWidth to the same value.

u

string

The url of the image to be used as the label content. Set its size by specifying both maxHeight and maxWidth. See Image labels for more details.

AnnotationLabel

Beta

Labels show information on annotations. The information can be in a format of text, font icons or images.

The t property for annotations accepts an object to add a single styled label, or an array of objects to add multiple styled labels.

let data = {
  type: 'LinkChart',
  items: [
    {
      id: 'annotation1',
      type: 'annotation',
      subject: 'node1',
      t: [
        {
          fi: { t: 'fas fa-exclamation-circle' },   // coloured font icon label
          fc: 'rgb(216, 30, 91)',
        },
        {
          t: 'Annotation Label',    // text label positioned vertically inline to the font icon
          position: { vertical: 'inherit' },
        },
      ],
    },
    {
      id: 'node1',    // node1 is the annotation subject
      type: 'node',
      c: 'rgb(45,105,160)',
    },
  ],
};

For more information about annotation labels, which behave just like regular node labels, see also Advanced label styling docs.

b

stringdefault: No border

The colour of the label border.

borderRadius

number | string | number[] | objectdefault: '0 0 0 0'

The label corner radius. Accepts a number to set radius to all corners, a string of space-separated numbers ( top left, top right, bottom right, bottom left), an array of comma-separated numbers, or an object setting values for properties such as topLeft or bottomRight.

bw

numberdefault: 4

The width of the label border.

fb

booleandefault: false

Whether the label should be in bold font.

fbc

stringdefault: transparent

The label background colour.

fc

stringdefault: black

The label font colour.

ff

string

The font family to use for the label. The default is inherited from the fontFamily setting of chart.options().

fi

FontIcon

The font icon to use as a label.

fs

number | "auto"default: 14

The label font size. Set to 'auto' to size the font automatically depending on the annotation size. Note that 'auto' font sizing shouldn't be used when parent annotation's width (w) and/or height (h) is also 'auto'.

margin

number | string | number[] | objectdefault: '0 0 0 0'

The distance between the label and another label or the parent annotation. Calculated outside of label or annotation borders.

See also Margin, padding and border for details and accepted value formats.

maxHeight

number

The maximum height of the label. Use this option when fs is set to 'auto' to set the maximum height of the text.

maxWidth

numberdefault: 240

The maximum width of the label. Set custom maxWidth when textWrap is set to 'normal' to reduce the maximum text width before a line break, or when fs is set to 'auto' to set the maximum text width.

minHeight

number | "stretch"default: 0

The minimum height of the label. Will always fit the content. Set to 'stretch' to draw the label across the whole annotation height.

minWidth

number | "stretch"default: 0

The minimum width of the label. Will always fit the content inside. Set to 'stretch' to draw the label across the whole annotation width. Set custom minWidth when textWrap is set to 'normal' to increase the minimum text width before a line break.

padding

number | string | number[] | objectdefault: '10 10 10 10'

The distance between the label content and the label edge. Borders are excluded.

See also Margin, padding and border for details and accepted value formats.

position

NodeLabelPosition

Sets the label position. Possible values are:

A string with a compass point value ( 'n', 'ne' etc.). Places labels outside the annotation.
An object with horizontal and/or vertical properties. Places labels inside the annotation. Note that if used with negative values to place the labels outside, the connector line will not avoid the labels.

Default annotation label position is { horizontal: 'centre', vertical: 'middle' }. See also Label positioning for details.

horizontal

"left" | "right" | "centre" | number

The horizontal position. The number in world coordinates sets the horizontal position of the label's top left corner in relation to the top left corner of the node/combo.

vertical

The 'inherit' value puts the label on the same line as the previous label:

t: [
  // label 1 has no vertical position, set label 2 to 'inherit' to place it inline
  { t: 'label 1' },
  { t: 'label 2', position: { vertical: 'inherit' } },
]

Similarly, setting two labels to the same vertical position will also put them on the same line:

t: [
  // set label 2 to the same vertical position as label 1 to place it inline
  { t: 'label 1', position: { vertical: 'bottom' } },
  { t: 'label 2', position: { vertical: 'bottom' } },
]

t

string

The label text.

textAlignment

object

The alignment of the content inside the label.

horizontal

"left" | "right" | "centre"default: 'left'

The horizontal alignment.

vertical

"top" | "bottom" | "middle"default: 'top'

The vertical alignment.

textWrap

"normal" | "initial"default: 'normal'

u

string

The url of the image to be used as the label content. Set its size by specifying both maxHeight and maxWidth. Align the image within the node using position and margin, and set a border with b, borderRadius, and bw.

Bubble

Deprecated

Bubbles are deprecated in favour of annotations, which are more modern and customisable.

Bubbles are sub-items that can be used to add additional text to nodes or links. You can only show one bubble per item.

Bubbles can be shown in one of four positions:

North East ('ne')
South East ('se')
South West ('sw')
North West ('nw')

Bubbles are added to items as follows:

let data = {
  type: 'LinkChart',
  items: [
    {
      id: 'node1', t: 'label', type: 'node', u: 'person.png', x: 100, y: 150,
      bu: {
        c: 'rgb(255, 0, 0)',  // the bubble fill colour
        p: 'ne',              // bubble in NE position. use 'se', 'sw', 'nw' for the other positions
        t: 'Bubble'           // the bubble text
      }
    }
  ]
};

b

string(Colour)default: 'grey'

The colour of the bubble border.

c

string(Colour)default: 'white'

The colour of the bubble fill.

fb

booleandefault: false

Whether the bubble text should be displayed in bold font.

fc

string(Colour)default: 'black'

The colour for the bubble text font.

ff

string

The font family to use for the bubble text. The default is inherited from the fontFamily setting of chart.options().

fs

numberdefault: 14

The font size (px) of the bubble text.

g

Glyph

An object describing the glyph shown in the bubble.

p

"ne" | "se" | "sw" | "nw"default: 'ne'

The position of the bubble relative to the node or link. The 4 positions are compass points.

t

required

string

The text for the bubble.

Glyph

Glyphs are sub-items displayed on nodes, links, annotations or combos to convey additional information such as a status or a counter.

A glyph can be a simple coloured circle, and/or show a font icon, an image or a text. If multiple types are set in the same glyph object, only one is shown in this order:

text t (highest priority)
image u
font icon fi
coloured circle c (lowest priority)

To move icons and images inside glyphs from their default positions, use the imageAlignment option.

Glyphs on Nodes and Annotations

Glyphs are drawn along a border of the annotation or node (incl. closed combo node). They are added as an array of objects to the g property.

There are two styles of positioning:

Compass points, e.g. 'n' for north, 'se' for south east etc.
Integers in the range 0-359, where numbers represent the angle from the centre of the item, measured in degrees clockwise from north.

Glyphs on a single node or annotation must use the same positioning method (i.e., all use compass points or all use angles). In an array, glyphs are only drawn if they use the same positioning method as the first glyph.

You can have as many glyphs as you like, but only one glyph is allowed in each position. If multiple glyphs are set in one position, only the first one is drawn.

let data = {
  type: 'LinkChart',
  items: [
    {
      id: 'node1',
      type: 'node',
      c: '#43976C',
      t: 'node label',
      g: [{
          p: 'ne',                        // north-east corner position, position required for nodes
          c: 'red',                       // fill colour required for text to show
          t: '!',                         // the glyph text
          border: { colour: 'orange' },   // the border around the glyph
      }],
    },
    {
      id: 'annotation1',
      type: 'annotation',
      subject: 'node1',
      t: { t: 'annotation label' },
      g: [{
          p: 'ne',
          c: 'blue',
          t: '!'
      }],
    },
]};

Glyphs on Links

Links can have any number of glyphs that can be added either in the centre or at the link ends (t1 and t2). Glyphs are added as an array of objects to the g property:

let data = {
  type: 'LinkChart',
  items: [
    { id: 'n1', type: 'node', c: '#43976C' },
    { id: 'n2', type: 'node', c: '#43976C' },
    {
      id: 'link1',
      type: 'link',
      id1: 'n1',
      id2: 'n2',
      t: 'link label',
      g: [
          { c: 'red', t: '!' },       // array of glyphs in the link centre,
          { c: 'orange', t: '!' },    // shown left to right
      ],
      t1: {
        g: [ 
          { c: 'blue', t: '!' }       // array of glyphs at the left link end, shown left to right
        ],
      },
}]};

Beta Glyphs on Open Combos

Glyphs are drawn along an open combo's border. Depending on how the combo was created, glyphs are added as an array of objects to the g property of the openStyle property or the oc property.

The positioning of glyphs on open combos is the same as the positioning of glyphs on nodes, which means that either compass points (e.g. 'n', 'e', 'se') or integers (in the range 0-359) can be used.

Glyphs on a single open combo must use the same style of positioning (i.e., all use compass points or all use angles). In an array, glyphs are only drawn if they use the same positioning method as the first glyph.

You can have as many glyphs as you like, but only one glyph is allowed in each position. If multiple glyphs are set in one position, only the first one is drawn.

Note: The r property is not supported for glyphs on open combos.

let data = {
  type: 'LinkChart',
   items: [
     {
       id: 'newcombo1',
       type: 'node',
       c: 'blue',
       oc: {
         g: [{
             p: 'nw',                // north-west corner position, position required for combos
             c: 'rgb(255, 0, 0)',    // fill colour required for text to show
             t: '!',                 // the glyph text
             border: {               // the border around the glyph
               colour: 'green',
               width: 4,
             },
         }],
       },
     },
     { id: 'newchild1', parentId: 'newcombo1', type: 'node', c: 'red' },
     { id: 'newchild2', parentId: 'newcombo1', type: 'node', c: 'red' },
   ],
};

a

booleandefault: false

Set to true for an animated glyph.

b

Deprecated

string(Colour)default: 'grey'

The glyph border colour. Borders on image glyphs without a glyph background are not supported. Deprecated as we recommend using border instead.

border

object

The border around the glyph. Borders on image glyphs without a glyph background are not supported. If both b and border are set, border takes precendence.

colour

string

The border colour.

width

numberdefault: 2

The border width. The maximum value is 18.

c

string(Colour)

The glyph fill colour. Required for text glyphs. If set for image and font icon glyphs, images and font icons are shown inside the glyph. If not set, images and font icons also replace the glyph background.

e

numberdefault: 1

The enlargement factor for the glyph.

fb

booleandefault: true

Whether the glyph's label should be displayed in bold.

fc

string(Colour)default: 'white'

The font colour for the glyph's label.

ff

string

The font family to use for the glyph's label. The default is inherited from the fontFamily setting of chart.options().

fi

FontIcon

The font icon to use for the glyph.

p

string | number

The position of the glyph relative to the node. Only supported and required on nodes and open combos. Use compass point strings ('n', 'se', etc.) or integer degrees clockwise from the top (in the range 0-359).

r

number

Overrides the distance from the centre of the node at which the glyph is drawn. Only available when the glyph's position is a number. If specified, link ends will no longer avoid the glyph. Not supported by open combos.

t

string

The text label to use for the glyph. Standard glyphs (where w is set to false) show a maximum of four characters. Wide glyphs (where w is set to true) show a maximum of 25 characters.

u

string

The URL of the image to use for the glyph. The image can be any size, but 64X64 should be adequate.

w

booleandefault: false

If true, the glyph width will adjust automatically to fit up to 25 characters, forming a rounded rectangle. Longer labels are truncated. Not supported by glyphs on links.

FontIcon

Font icons are vector-based glyphs embedded in font files, where specific character codes are mapped to icons.

In KeyLines, font icons can be used as node icons, glyph icons (on nodes, links, annotations and combos) and label icons (in node and annotation labels).

You can position and scale them using the imageAlignment chart option and dynamically change their fill colour using the c property.

To use font icons, you must install them in your application, import and load them into KeyLines and set them in the iconFontFamily option. See Fonts and Font Icons for details.

The referenced icons must be on the same domain as the KeyLines library, otherwise your browser will mark them as insecure and prevent them from loading. See Cross-Origin Images (CORS) for details.

let data = {
  type: 'LinkChart',
  items: [
    {
      id: 'user471',
      type: 'node',
      c: 'green',                                                //  green node
      fi: { c: 'white', t: 'fas fa-user' },                      //  white font icon inside the node
      g: [
        {
          fi: { c: 'red', t: 'fas fa-exclamation-triangle' },    // red glyph icon   
          p: 'ne',                                               // in north-east corner position of node
        },
      ],
      t: [
        {
          t: 'Membership Expired: 01/2025',
          position: 's',
        },
        {
          fi: { c: 'red', t: 'fas fa-exclamation-triangle' },    // red glyph icon  
          position: { vertical: 'inherit' },                     // placed inline following the text label
        },
      ],
    },
  ],
};

If an image is also specified for a node in the u property, the image takes precedence and the font icon is ignored.

c

string(Colour)default: 'black'

The font icon fill colour.

ff

string

The font family to use for the font icon. The default is inherited from iconFontFamily.

t

required

string | number

The font icon to show. Pass in a CSS class name or an escaped Unicode code point, e.g. '\u{f007}'.

Halo

Halos are circular rings that can be added to nodes. A node can have up to ten halos, on properties named ha0 to ha9.

Halos are added to nodes as follows:

let data = {
 type: 'LinkChart',
 items: [
   {
     id: 'node1', t: 'label', type: 'node', u: 'person.png', x: 100, y: 150,
     ha0: {
       c: 'rgb(0, 0, 255)',    // the halo fill colour
       r: 100,                 // the halo radius
       w: 20                   // the halo width
     }
   }
 ]
};

Setting the halo object to null or undefined removes the halo.

c

required

string(Colour)

The colour of the halo.

r

required

number

The radius of the halo.

w

required

number

The width of the halo.

Donut

Nodes can have donuts around their borders. They can be split into segments to represent relative quantities, similar to the way sectors work on a pie chart. Donuts cannot be added to nodes with sh property set to 'box'.

Donuts are added to nodes as follows:

let data = {
 type: 'LinkChart',
 items: [
   {
     id: 'node1', type: 'node', c: '#aaa', x: 100, y: 150,
     donut: {
       // the values for each donut segment
       v: [10, 30, 25, 40, 15],
       // the colour for each donut segment
       c: ['#e41a1c', '#377eb8', '#4daf4a', '#984ea3', '#ff7f00'],
       w: 12,         // the width of the donut segments
       b: 'black',    // the colour of the border between segments
       bw: 1          // the width of the border between segments
     }
   }
 ]
};

b

string(Colour)default: 'white'

The colour of the border between donut segments.

bw

numberdefault: 2

The width of the border between donut segments.

c

string(Colour)default: standard colours

An array giving the colour of each segment. It should contain the same number of elements as the v array. If not supplied, a default set of colours is used.

v

required

number[]

An array giving the size of each segment. Values must be positive. Segments are positioned clockwise around the node starting at the top. Do not animate changes that add or remove segments.

w

numberdefault: 10

The width of the donut segments. This doesn't include the border.

TimeBarItem

The time bar object lets you load JSON data in the following format into the time bar:

let data = {
 items: [
   { id: 'id1',     // 'id1' is the identity that the item relates to
     dt: [...],     // a timestamp or array of timestamps - either Date objects or numbers
     v:  [...],     // an optional value or array of values for each timestamp
                    // values must be numbers, there must be one for each timestamp
   },
   { id: 'id2',
     dt: [...],
     v:  [...]
   },
   ...
 ]
};

Time bar object properties are designed so that exactly the same data object can be loaded into both the chart and the time bar. Simply add the dt and optional v properties to the items.

d

object

The d parameter stands for data. Use this to store custom data on the item.

dt

required

The time entry or time entries associated with this item. Either a single time entry or an array of time entries may be supplied. Each time entry may be either a JavaScript Date object, a millisecond number, or a TimePeriod object. See the Time Zones and JavaScript page for more details.

id

required

string

The id that the item is associated with. It must not end with a '\' character.

v

number | number[]default: 1

The value associated with each time entry, for example, the amount of a transaction. Values must be greater than zero. The same number of values should be supplied as the number of time entries. If values are not supplied, then the time bar counts the number of timestamps, instead of adding up the corresponding values.

TimePeriod

Each time bar item has a dt property that holds a time bar entry or an array of time bar entries. Each entry may be one of the following:

a Date object or millisecond number, representing an instant in time
a TimePeriod object, representing a period of time

The TimePeriod object has dt1 and dt2 properties that set the start and end of the time period.

To represent an open-ended time period, set the dt1 property only. To represent a time period without a start time, set the dt2 property only.

dt1

number | Date

The timestamp for the start of the time period, with numbers evaluated as milliseconds.

dt2

number | Date

The timestamp for the end of the time period, with numbers evaluated as milliseconds.

Colour

Colourstring

Colours can be specified in several formats:

One of the 17 CSS standard named colours, e.g., 'red'
Shorthand hexadecimal colours, e.g., '#F00'
Hexadecimal colours, e.g., '#FF0000'
rgb or rgba formats. For example

'rgb(255, 0, 0)' - Red
'rgba(255, 0, 0, 0.5)' - Red with an alpha blend of 50%

Note that the 130 extended CSS named colours are not supported.

IdMap

IdMaps are objects containing properties where property names are ids of items and property values are the values assigned to the respective items.

const degreesResult = {
  node1id: node1degree,
  node2id: node2degree,
  ...
}