Chart Options

These are the options you can pass to the first argument of chart.options().

For an example of how these options work, see Styling Charts.

aggregateLinks

Beta

boolean | AggregateLinksOptionsdefault: false

Controls whether one or more links between a pair of nodes are displayed as an aggregate link. Set to true to aggregate all the links between each pair of nodes or set the options below to specify how links should be aggregated.

Also note that:

Graph functions ignore aggregate links and calculate the results based on the unaggregated chart.
Hiding or backgrounding aggregate links is done by hiding or backgrounding all of their child links. See Inheriting state from child links.

aggregateBy

string

The key of the custom data on the child link's d property to be used to aggregate links together. One aggregate link is created between two nodes for each value of the data. Remove the d property or set it to undefined to prevent the link from being aggregated.

aggregateByDirection

booleandefault: false

Controls whether separate aggregate links are created for each of the directions the child links could have ('from', 'to', 'both' or 'neither').

arrows

"small" | "normal" | "large" | "xlarge"default: 'normal'

Controls the appearance of arrows on links. Arrowhead size is also proportional to the link width w.

backColour

string(Colour)default: 'white'

The colour to use for the chart background.

backgroundAlpha

numberdefault: 0.2

The alpha value to apply to backgrounded items, in the range 0 to 1.

bands

Bands

Set to give the chart a set of labelled vertical background bands.

Note that bands on a Leaflet map are not supported.

const options = { bands: { top: true, bottom: true, bands: [{ x: 100, w: 100, c: '#F0F0F0', t: 'Band 1' }, { x: 200, w: 100, c: '#F8F8F8', t: 'Band 2' }] } };
chart.options(options);

bands

Band[]

An array of objects defining each of the bands.

c

stringdefault: 'light grey'

The colour of the band.

fb

booleandefault: false

Whether the band label should be displayed in bold font.

fc

stringdefault: 'light grey'

The colour for the band label font.

ff

string

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

fs

numberdefault: 20

The font size (px) of the band label. The size may be reduced to fit the label in the band.

t

string

The text of the band label.

w

numberdefault: 100

The width of the band, in world coordinates.

x

numberdefault: 0

The position of the centre of the band along the X-axis, in world coordinates.

bottom

booleandefault: false

Whether labels are displayed at the bottom of the bands.

top

booleandefault: true

Whether labels are displayed at the top of the bands.

combos

ChartComboOptions

Controls the shape of open combos.

shape

required

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

Sets the shape of all open chart combos.

controlColour

string(Colour)

The rgb colour to use for the navigation and overview window controls. Only the hue and saturation of the colour are used: the lightness is fixed. To further customise the overview window, use the backColour and borderColour properties.

controlTheme

"light" | "dark"default: 'light'

The colour theme of the navigation and overview window controls.

defaultStyles

StyleOptions

Settings to control the default style of certain chart objects.

comboGlyph

Glyph | null

Sets the style of the counter glyph. The default is red in the top right corner showing the number of nodes contained within the combo.

comboGlyphOnOpen

Beta

booleandefault: false

Controls whether or not the counter glyph is shown on open combos.

comboLinks

ComboLinkStyle

Styling options for combo links created by chart.combo().combine(), or by adding new links. Any unspecified properties are inherited from the styling of a link contained in the combo. See Link for default values.

b1

number

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

number

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.

c

string(Colour)

The colour of the link.

ls

"solid" | "dashed" | "dotted"

The style of the link line.

w

number

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

openCombos

OpenStyleOptions

Settings for the open style of combos. Accepts all options of the oc property except for the t option.

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.

drag

DragOptions

Settings to control how dragging operations work in the chart.

links

required

booleandefault: false

Controls if links will be offset when selected and dragged. If false, links can be selected but not dragged. If true, links can be dragged. Dragging of self links is not possible.

panAtBoundary

required

booleandefault: true

If true, the chart automatically pans when dragging an item near the boundary of the visible chart area.

fontFamily

stringdefault: 'sans-serif'

The default font family to use, for example 'helvetica'.

gradient

Gradient

Set to give the chart a background gradient fill that runs from top to bottom of the chart. Note that backColour property takes precedence over the gradient property.

const options = { gradient: { stops: [{ r: 0, c: 'rgb(250, 250, 250)' }, { r: 1, c: 'rgb(200, 200, 200)' }] } };
chart.options(options);

stops

required

GradientColour[]

Defines the gradient colours.

c

required

string

The colour to apply at the corresponding r value.

r

required

number

Defines how far down the background the corresponding colour should apply. Should be between 0 and 1.

handMode

booleandefault: false

Controls the default behaviour of navigation:

If true, dragging over the background pans the view.
If false, dragging over the background creates a selection marquee.

hover

numberdefault: 150

The number of milliseconds delay before the hover event is triggered.

iconFontFamily

stringdefault: 'sans-serif'

The default font family to use for font icons, for example 'Font Awesome 6 Free' or 'Material Icons Outlined'.

imageAlignment

IdMap

Sets the position and scale for images and font icons on nodes. The object accepts properties where property names are image or font icon paths and property values are the values to be adjusted:

chart.options({
  imageAlignment: {
    'fas fa-user': { e: 0.8, dx: 5 },
    '/images/icons/person4.png': { dx: -20, dy: 5, e: 2.5 }
  }
});

When using images and font icons in label objects for node and annotation labels, image alignment is handled differently. See Image labels and Text-based labels.

dx

numberdefault: 0

The horizontal offset as a percentage value of the item's size. The range is -50 to 50.

dy

numberdefault: 0

The vertical offset as a percentage value of the item's size. The range is -50 to 50.

e

numberdefault: 1

The enlargement factor of the item relative to its parent. Must be greater than 0.

labelOffset

number

An integer to move the label text up or down. Useful only for certain fonts where the baseline is irregular (e.g. Open Sans).

legacyGlyphAndLabelOrdering

booleandefault: false

If set to true, labels are drawn over glyphs. If false, glyphs are drawn over labels.

legacyShapeNodeBehaviour

booleandefault: false

If set to true, nodes with w and h specified are drawn behind other chart items as legacy shape nodes.

linkEnds

LinkEnds

Settings that control how the ends of links are drawn.

avoidLabels

booleandefault: true

Whether link ends should avoid node labels. Does not apply to labels positioned by numeric values in the positions object.

spacing

"loose" | "tight"default: 'tight'

Controls the spacing between nodes and link ends connected to them. If set to 'loose', there is a small gap between the node and the link end. Also affects the spacing between node subjects and annotation lines.

linkStyle

LinkStyleOptions

Settings to control how links are drawn.

glyphs

"horizontal" | "along"default: 'horizontal'

Controls the positioning of multiple glyphs on links without labels.

'along' - glyphs are drawn along the link.
'horizontal' - glyphs are drawn horizontally.

inline

booleandefault: false

Controls the orientation of labels, glyphs and bubbles on links. When true, sub-items are rotated to match the link orientation. Note that enabling this option overrides the glyphs option.

path

Deprecated

"direct" | "horizontal" | "vertical"default: 'direct'

Controls the shape of links. Most effective with sequential layouts. Deprecated as we recommend using the linkShape option instead.

'direct' - links are either straight or follow arcs when offset.
'horizontal' - link ends join to nodes horizontally, following a curved path.
'vertical' - link ends join to nodes vertically, following a curved path.

The 'horizontal' and 'vertical' shapes will not apply to links within combos.

transition

numberdefault: 0.75

Only for links with a colour gradient (c2 property set). Controls the size of the fraction at the midpoint of the link where the colour transition occurs. Must be between 0 and 1, with 0 providing an immediate transition between colours. The rest of the link is drawn with solid colours.

logo

Logo

Settings for the logo to be displayed in a corner of the chart.

const options = { logo: { u: 'path/to/images/myAwesomeLogo.png', p: 'se', x: 20, y: 20 } };
chart.options(options);

p

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

The position of the logo.

u

null | string

The URL of the logo to be displayed, or null for no logo. On Retina devices, KeyLines will also check for a double-resolution @2x version of the logo, e.g. path/to/images/[email protected]

x

numberdefault: 0

The horizontal offset in pixels from the logo's default position.

y

numberdefault: 0

The vertical offset in pixels from the logo's default position.

marqueeLinkSelection

"off" | "centre" | "ends"default: 'centre'

Controls which part (or parts) of a link needs to be included within a selection marquee for the link to be selected. When set to 'off', links cannot be selected by a selection marquee.

maxItemZoom

numberdefault: 4

Sets the maximum zoom for items, from minZoom to 4. Using the default value is suggested for optimal result.

minZoom

numberdefault: 0.05

Sets the minimum zoom for the view. Use a smaller value to allow the chart to be zoomed out further. The value can be from 0.001 to 1.

object | boolean

Settings for the navigation controls.

const options = { navigation: { p: 'ne', shown: true, x: 10, y: 15 } };
chart.options(options);

If you don't want navigation controls on your chart, or you'd prefer to add custom controls, use:

const options = { navigation: false };
chart.options(options);

See the Social Network Analysis demo for examples how to customise navigation controls.

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

The position of the navigation controls.

booleandefault: true

Whether the navigation controls are displayed.

numberdefault: 0

The horizontal offset in pixels from the navigation controls' default position.

numberdefault: 0

The vertical offset in pixels from the navigation controls' default position.

overview

object | boolean

Settings for the overview window. To hide the overview window, you can set it to false. Overview window is not supported on a Leaflet map.

backColour

string(Colour)default: value of chart backColour

The background colour of the overview window. If an rgba colour is used, the alpha channel is ignored.

borderColour

string(Colour)default: 'light grey'

The colour of the border and view marker of the overview window.

icon

booleandefault: true

Whether the icon to toggle opening/closing the overview window is shown. Setting this to false when shown is false hides the overview window.

p

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

The position of the overview window.

shown

booleandefault: false

If set to true, the overview window is fully expanded. If false, the overview window is collapsed into an icon.

size

numberdefault: 100

The size of the overview window in pixels.

selectedLink

object | null

Styling options for selected links. If a link is selected and:

selectedLink is null or undefined - Selected links have a coloured selection circle and font background fbc set by selectionColour and a font colour fc set by selectionFontColour.
selectedLink and selectionColour / selectionFontColour have different values - selectedLink takes precedence.
selectedLink is partially set - any values unset are inherited from the unselected link styling.

If the selected link has t1 and/or t2 set, their styling is the first specified of:

t1 / t2 of selectedLink
t1 / t2 of the unselected link
selectedLink values
Link values

Note that if t1 / t2 inherit the styling from the border object from any of the above, any unspecified values will be set to defaults.

b1

number

The distance to back-off from end id1 as a ratio of the total length of the link line. Must be between 0 and 1.

b2

number

The distance to back-off from end id2 as a ratio of the total length of the link line. Must be between 0 and 1.

border

LinkLabelBorder

The border around the link label.

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.

c

string(Colour)

The colour of the link.

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.

fb

boolean

Whether the label should be displayed in bold font.

fbc

string(Colour)

The background colour of the font. The default is inherited from selectionColour.

fc

string(Colour)

The colour of the label font. The default is inherited from selectionFontColour.

ff

string

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

flow

boolean | FlowOptions

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

number

The font size (px) of the link label.

ls

"solid" | "dashed" | "dotted"

The style of the link line.

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.

priority

Beta

0 | 1default: 0

The priority of the link; see Prioritising links.

t1

string | LinkEndLabel

The link label at the id1 end. For multiline labels, use '\n' or '\r' to force a line break. Strings inherit properties from the label at the centre of the link.

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 at the id2 end. For multiline labels, use '\n' or '\r' to force a line break. Strings inherit properties from the label at the centre of the link.

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.

w

number

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

selectedNode

object | null

Styling options for selected nodes:

If selectedNode is null or undefined - Selected nodes have a default border b and font background fbc set by selectionColour and a font colour fc set by selectionFontColour.
If different values are set in selectedNode and selectionColour / selectionFontColour - selectedNode values take precedence.

If selectedNode is only partially set, any values unset are inherited from the unselected node's styling. See Node for default values.

b

string(Colour)

The border colour. The default is inherited from selectionColour.

bs

"solid" | "dashed"

The style of the border line.

bw

number

The width of the node's border.

c

string(Colour)

The node background fill colour.

e

number

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

fb

boolean

Whether the label should be displayed in bold font.

fbc

string(Colour)

The background colour of the font. When overriding properties on a node that contains a Node Label object or array of objects, the change only applies if the fbc property was set on the top node level or to those labels that don't have a set fbc property.

The default is inherited from selectionColour.

fc

string(Colour)

The colour of the label font. When overriding properties on a node that contains a Node Label object or array of objects, the change only applies if the fc property was set on the top node level or to those labels that don't have a set fc property.

The default is inherited from selectionFontColour.

ff

string

The font family to use for the label.

fi

FontIcon

The font icon used on the node.

fs

number

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

ha0-9

Halo

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

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'

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.

re

Deprecated

boolean

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.

tc

Deprecated

boolean

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.

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.

selectionColour

string(Colour)default: 'rgb(114, 179, 0)'

The default colour to use for highlighting selected nodes and links. Includes the node border and font background for nodes and a coloured circle and font background for links. Only applies to nodes and/or links if selectedNode and/or selectedLink are null or undefined.

selectionFontColour

string(Colour)default: 'rgb(255, 255, 255)'

The default font colour to use for selected nodes and links. Only applies to nodes and/or links if selectedNode and/or selectedLink are null or undefined.

selfLinks

booleandefault: false

If true, links from a node to itself can be added to the chart. If false, self links are not loaded into the model.

truncateLabels

object

Controls how node and link labels are truncated. If not set, labels are not truncated.

maxLength

numberdefault: 30

The maximum character length of a node or link label before it is truncated. If set, labels are truncated to the length specified, and the last three characters are replaced with ....

showOnHover

booleandefault: true

If true, hovering over a node or a link reveals the full length of all their truncated labels. Use the hover option to change the hover interval. Not supported on touch devices.

watermark

WatermarkOptions

An object whose properties are the settings for a watermark on the chart.

Note that watermarks on a Leaflet map are not supported.

const options = { watermark: { a: 'top', fb: true, fs: 15, fc: 'black', t: 'A custom watermark' } };
chart.options(options);