Charts

Parameters

target string | Element

data LineChartData

options? LineChartPresetOptions = {}

responsiveOptions? PresetResponsiveOptions<LineChartPresetOptions>

Parameters

target string | Element

data BarChartData

options? BarChartPresetOptions = {}

responsiveOptions? PresetResponsiveOptions<BarChartPresetOptions>

Parameters

target string | Element

data PieChartData

options? PieChartPresetOptions = {}

responsiveOptions? PresetResponsiveOptions<PieChartPresetOptions>

Properties

labels? Label[]

One label per value position: the steps of the X axis in line and bar charts, the slices in pie charts.

series T

The values: an array per series (or a series object with a name, class name and meta), or one flat array for pies and distributed bars.

Properties

classNames? { … }

The class names of the chart's elements. Change them to style the chart with your own CSS instead of Chartist's.

classNames.chart? string default 'ct-chart-line'

The chart's SVG element.

classNames.label? string default 'ct-label'

Each axis label.

classNames.labelGroup? string default 'ct-labels'

The group of an axis's labels.

classNames.series? string default 'ct-series'

The group of each series.

classNames.line? string default 'ct-line'

Each line.

classNames.point? string default 'ct-point'

Each point.

classNames.area? string default 'ct-area'

Each area.

classNames.grid? string default 'ct-grid'

Each grid line.

classNames.gridGroup? string default 'ct-grids'

The group of the grid lines.

classNames.gridBackground? string default 'ct-grid-background'

The grid background (with showGridBackground).

classNames.vertical? string default 'ct-vertical'

Labels and grid lines of the vertical axis.

classNames.horizontal? string default 'ct-horizontal'

Labels and grid lines of the horizontal axis.

classNames.start? string default 'ct-start'

Labels at the start of their axis (left or top).

classNames.end? string default 'ct-end'

Labels at the end of their axis (right or bottom).

showLine? boolean default true

Draws the lines.

showPoint? boolean default true

Draws a point at each value.

showArea? boolean default false

Fills the area between each line and areaBase.

areaBase? number default 0

The value the areas close at, usually 0.

lineSmooth? boolean | LineInterpolation default true

How a line runs between its points: true smooths it with Interpolation.monotoneCubic, false draws straight segments (Interpolation.none), or pass an interpolation such as Interpolation.cardinal(), Interpolation.step() or your own.

showGridBackground? boolean default false

Fills the grid area with a background (class ct-grid-background).

fullWidth? boolean default false

Stretches the X axis so the last value lands on the right edge, without a last grid line. The last label may need chart padding to fit.

reverseData? boolean default false

Reverses the labels, the order of the series and each series' values.

width? string | number

The chart's width: px as a number, or a CSS length such as '100%'. Without it, the chart takes the width of its container.

height? string | number

The chart's height: px as a number, or a CSS length such as '300px'. Without it, the chart takes the height of its container.

low? number

The lowest value the value axis shows, instead of the data's lowest. Values below it are drawn outside the drawing area.

high? number

The highest value the value axis shows, instead of the data's highest. Values above it are drawn outside the drawing area.

referenceValue? number

A value the value axis always includes, such as 0, so it shows even when all values are above or below it. Bar charts use 0.

chartPadding? number | Partial<ChartPadding> default { top: 15, right: 15, bottom: 5, left: 10 }

Space in px between the chart's edges and its drawing area (labels sit in it): one number for every side, or an object with some sides.

viewBox? ViewBox

A viewBox for the SVG, so the drawing scales with its box instead of being drawn for its size. Text scales too: adjust it with responsive options.

viewBox.width number

The viewBox width, in SVG units.

viewBox.height number

The viewBox height, in SVG units.

readonly plugins? readonly PluginEntry[]

v2 plugins; convert 1.x plugins with fromLegacyPlugin.

readonly on? PhaseListeners

Phase listeners by phase name (or '*' for all phases), as on in the config of chart(). They're registered before the first render, so they see it too.

on.*? AllPhasesListener

Listens to every phase, with the phase name as first argument.

readonly series? Readonly<Record<string, LineSeriesOptions>>

Options per series name: only these five apply per series.

readonly axisX? PresetAxisOptions & Omit<NonNullable<LineChartOptions['axisX']>, 'type'>

Options of the X axis; its type may also be a v2 axis factory.

axisX.low? number

The lowest value this axis shows, instead of the data's lowest.

axisX.high? number

The highest value this axis shows, instead of the data's highest.

axisX.referenceValue? number

A value this axis always includes, such as 0.

axisX.offset? number default 30

Room in px for the axis labels, between the drawing area and the chart's edge.

axisX.position? 'end' | 'start' default 'end'

Where the labels go: start (left or top) or end (right or bottom).

axisX.labelOffset? { x: number; y: number } default { x: 0, y: 0 }

Moves the labels by x and y px from where they'd go.

axisX.showLabel? boolean default true

Draws the axis labels.

axisX.showGrid? boolean default true

Draws the grid lines of the axis.

axisX.labelInterpolationFnc? (value: Label, index: number) => Label | null | undefined

Turns each label (and its index) into the text to show. Return null or undefined to leave a label out.

axisX.scaleMinSpace? number

The minimum space in px between two grid lines of a scale: the scale takes fewer, larger steps to keep it.

axisX.onlyInteger? boolean

Only whole numbers on the scale.

axisX.ticks? Label[]

The ticks: the labels of a step axis, or the values of a fixed scale axis.

axisX.stretch? boolean

Step axis: spreads the ticks over the whole axis, so the last one lands on its end (line charts with fullWidth set it).

axisX.divisor? number

Fixed scale axis without ticks: the number of equal steps between its low and high, with a tick at each end.

axisX.highLow? { high: number; low: number }

The value range of a scale as { high, low }, instead of the one computed from the data.

axisX.type? AxisSetup['type']

A v2 axis factory or a 1.x axis class.

readonly axisY? PresetAxisOptions & Omit<NonNullable<LineChartOptions['axisY']>, 'type'>

Options of the Y axis; its type may also be a v2 axis factory.

axisY.low? number

The lowest value this axis shows, instead of the data's lowest.

axisY.high? number

The highest value this axis shows, instead of the data's highest.

axisY.referenceValue? number

A value this axis always includes, such as 0.

axisY.offset? number default 40

Room in px for the axis labels, between the drawing area and the chart's edge.

axisY.position? 'end' | 'start' default 'start'

Where the labels go: start (left or top) or end (right or bottom).

axisY.labelOffset? { x: number; y: number } default { x: 0, y: 0 }

Moves the labels by x and y px from where they'd go.

axisY.showLabel? boolean default true

Draws the axis labels.

axisY.showGrid? boolean default true

Draws the grid lines of the axis.

axisY.labelInterpolationFnc? (value: Label, index: number) => Label | null | undefined

Turns each label (and its index) into the text to show. Return null or undefined to leave a label out.

axisY.scaleMinSpace? number default 20

The minimum space in px between two grid lines of a scale: the scale takes fewer, larger steps to keep it.

axisY.onlyInteger? boolean default false

Only whole numbers on the scale.

axisY.ticks? Label[]

The ticks: the labels of a step axis, or the values of a fixed scale axis.

axisY.stretch? boolean

Step axis: spreads the ticks over the whole axis, so the last one lands on its end (line charts with fullWidth set it).

axisY.divisor? number

Fixed scale axis without ticks: the number of equal steps between its low and high, with a tick at each end.

axisY.highLow? { high: number; low: number }

The value range of a scale as { high, low }, instead of the one computed from the data.

axisY.type? AxisSetup['type']

A v2 axis factory or a 1.x axis class.

readonly labels? LabelMode

HTML (1.x) or SVG text labels; default: the renderer's mode.

Properties

labels? Label[]

One label per value position: the steps of the X axis in line and bar charts, the slices in pie charts.

series T

The values: an array per series (or a series object with a name, class name and meta), or one flat array for pies and distributed bars.

Properties

classNames? { … }

The class names of the chart's elements. Change them to style the chart with your own CSS instead of Chartist's.

classNames.chart? string default 'ct-chart-bar'

The chart's SVG element.

classNames.horizontalBars? string default 'ct-horizontal-bars'

The chart's SVG element, with horizontalBars.

classNames.label? string default 'ct-label'

Each axis label.

classNames.labelGroup? string default 'ct-labels'

The group of an axis's labels.

classNames.series? string default 'ct-series'

The group of each series.

classNames.bar? string default 'ct-bar'

Each bar.

classNames.grid? string default 'ct-grid'

Each grid line.

classNames.gridGroup? string default 'ct-grids'

The group of the grid lines.

classNames.gridBackground? string default 'ct-grid-background'

The grid background (with showGridBackground).

classNames.vertical? string default 'ct-vertical'

Labels and grid lines of the vertical axis.

classNames.horizontal? string default 'ct-horizontal'

Labels and grid lines of the horizontal axis.

classNames.start? string default 'ct-start'

Labels at the start of their axis (left or top).

classNames.end? string default 'ct-end'

Labels at the end of their axis (right or bottom).

seriesBarDistance? number default 15

The distance in px between the bars of a group (one bar per series).

stackBars? boolean default false

Stacks the bars of a group on each other; stackMode says how.

horizontalBars? boolean default false

Draws horizontal bars. The axes swap: the Y axis shows the labels and the X axis the values, so swap their options too.

distributeSeries? boolean default false

Treats one flat array of values as one series per value, each in its own color: a profile rather than values over time.

reverseData? boolean default false

Reverses the labels, the order of the series and each series' values.

showGridBackground? boolean default false

Fills the grid area with a background (class ct-grid-background).

width? string | number

The chart's width: px as a number, or a CSS length such as '100%'. Without it, the chart takes the width of its container.

height? string | number

The chart's height: px as a number, or a CSS length such as '300px'. Without it, the chart takes the height of its container.

low? number

The lowest value the value axis shows, instead of the data's lowest. Values below it are drawn outside the drawing area.

high? number

The highest value the value axis shows, instead of the data's highest. Values above it are drawn outside the drawing area.

referenceValue? number default 0

A value the value axis always includes, such as 0, so it shows even when all values are above or below it. Bar charts use 0.

chartPadding? number | Partial<ChartPadding> default { top: 15, right: 15, bottom: 5, left: 10 }

Space in px between the chart's edges and its drawing area (labels sit in it): one number for every side, or an object with some sides.

viewBox? ViewBox

A viewBox for the SVG, so the drawing scales with its box instead of being drawn for its size. Text scales too: adjust it with responsive options.

viewBox.width number

The viewBox width, in SVG units.

viewBox.height number

The viewBox height, in SVG units.

readonly plugins? readonly PluginEntry[]

v2 plugins; convert 1.x plugins with fromLegacyPlugin.

readonly on? PhaseListeners

Phase listeners by phase name (or '*' for all phases), as on in the config of chart(). They're registered before the first render, so they see it too.

on.*? AllPhasesListener

Listens to every phase, with the phase name as first argument.

readonly stackMode? 'accumulate' | 'accumulate-relative' | 'overlap' | boolean default 'accumulate'

How stacked bars stack: accumulate (default), accumulate-relative (positives up, negatives down), or overlap (also true): every bar from zero.

readonly axisX? PresetAxisOptions & Omit<NonNullable<BarChartOptions['axisX']>, 'type'>

Options of the X axis; its type may also be a v2 axis factory.

axisX.low? number

The lowest value this axis shows, instead of the data's lowest.

axisX.high? number

The highest value this axis shows, instead of the data's highest.

axisX.referenceValue? number

A value this axis always includes, such as 0.

axisX.offset? number default 30

Room in px for the axis labels, between the drawing area and the chart's edge.

axisX.position? 'end' | 'start' default 'end'

Where the labels go: start (left or top) or end (right or bottom).

axisX.labelOffset? { x: number; y: number } default { x: 0, y: 0 }

Moves the labels by x and y px from where they'd go.

axisX.showLabel? boolean default true

Draws the axis labels.

axisX.showGrid? boolean default true

Draws the grid lines of the axis.

axisX.labelInterpolationFnc? (value: Label, index: number) => Label | null | undefined

Turns each label (and its index) into the text to show. Return null or undefined to leave a label out.

axisX.scaleMinSpace? number default 30

The minimum space in px between two grid lines of a scale: the scale takes fewer, larger steps to keep it.

axisX.onlyInteger? boolean default false

Only whole numbers on the scale.

axisX.ticks? Label[]

The ticks: the labels of a step axis, or the values of a fixed scale axis.

axisX.stretch? boolean

Step axis: spreads the ticks over the whole axis, so the last one lands on its end (line charts with fullWidth set it).

axisX.divisor? number

Fixed scale axis without ticks: the number of equal steps between its low and high, with a tick at each end.

axisX.highLow? { high: number; low: number }

The value range of a scale as { high, low }, instead of the one computed from the data.

axisX.type? AxisSetup['type']

A v2 axis factory or a 1.x axis class.

readonly axisY? PresetAxisOptions & Omit<NonNullable<BarChartOptions['axisY']>, 'type'>

Options of the Y axis; its type may also be a v2 axis factory.

axisY.low? number

The lowest value this axis shows, instead of the data's lowest.

axisY.high? number

The highest value this axis shows, instead of the data's highest.

axisY.referenceValue? number

A value this axis always includes, such as 0.

axisY.offset? number default 40

Room in px for the axis labels, between the drawing area and the chart's edge.

axisY.position? 'end' | 'start' default 'start'

Where the labels go: start (left or top) or end (right or bottom).

axisY.labelOffset? { x: number; y: number } default { x: 0, y: 0 }

Moves the labels by x and y px from where they'd go.

axisY.showLabel? boolean default true

Draws the axis labels.

axisY.showGrid? boolean default true

Draws the grid lines of the axis.

axisY.labelInterpolationFnc? (value: Label, index: number) => Label | null | undefined

Turns each label (and its index) into the text to show. Return null or undefined to leave a label out.

axisY.scaleMinSpace? number default 20

The minimum space in px between two grid lines of a scale: the scale takes fewer, larger steps to keep it.

axisY.onlyInteger? boolean default false

Only whole numbers on the scale.

axisY.ticks? Label[]

The ticks: the labels of a step axis, or the values of a fixed scale axis.

axisY.stretch? boolean

Step axis: spreads the ticks over the whole axis, so the last one lands on its end (line charts with fullWidth set it).

axisY.divisor? number

Fixed scale axis without ticks: the number of equal steps between its low and high, with a tick at each end.

axisY.highLow? { high: number; low: number }

The value range of a scale as { high, low }, instead of the one computed from the data.

axisY.type? AxisSetup['type']

A v2 axis factory or a 1.x axis class.

readonly labels? LabelMode

HTML (1.x) or SVG text labels; default: the renderer's mode.

Properties

labels? Label[]

One label per value position: the steps of the X axis in line and bar charts, the slices in pie charts.

series T

The values: an array per series (or a series object with a name, class name and meta), or one flat array for pies and distributed bars.

Properties

classNames? { … }

The class names of the chart's elements. Change them to style the chart with your own CSS instead of Chartist's.

classNames.chartPie? string default 'ct-chart-pie'

The chart's SVG element, for pies.

classNames.chartDonut? string default 'ct-chart-donut'

The chart's SVG element, for donuts.

classNames.series? string default 'ct-series'

The group of each series.

classNames.slicePie? string default 'ct-slice-pie'

Each pie slice.

classNames.sliceDonut? string default 'ct-slice-donut'

Each donut slice.

classNames.label? string default 'ct-label'

Each axis label.

startAngle? number default 0

Where the first slice starts, in degrees clockwise from the top.

total? number

The value a full circle stands for. With a total above the sum of the values, the pie stays open, as for a gauge.

donut? boolean default false

Draws a donut: rings instead of filled slices.

donutWidth? string | number

The width of a donut's ring: px as a number, or a share of the radius as a string ('30%'). Without it, the stylesheet sets the width (--ct-donut-width, 60px by default), and in the browser the ring is laid out for the width the stylesheet gives a slice. Without a DOM (renderToString()), it's laid out for 60 px.

showLabel? boolean default true

Draws a label for each slice.

labelOffset? number default 0

Moves the labels away from the center (positive) or toward it (negative), in px.

labelPosition? RadialLabelPosition default 'inside'

Where labels go: inside (halfway out on a pie, on the middle of a donut's ring, plus labelOffset), outside (at the outer edge) or center (in the middle; move them with labelOffset).

labelInterpolationFnc? (value: Label, index: number) => Label | null | undefined

Turns each slice's label (or value) and index into the text to show. Return null or undefined to leave a label out.

labelDirection? LabelDirection default 'neutral'

Which way labels anchor: neutral, explode (away from the center, for labels outside the pie) or implode (toward it).

ignoreEmptyValues? boolean default false

Leaves out the slices and labels of empty values.

preventOverlappingLabelOffset? number default 0

Moves labels apart so they don't overlap, using this offset in px. The overlap is judged by the length of the drawn label text. 0 leaves them where they are.

width? string | number

The chart's width: px as a number, or a CSS length such as '100%'. Without it, the chart takes the width of its container.

height? string | number

The chart's height: px as a number, or a CSS length such as '300px'. Without it, the chart takes the height of its container.

low? number

The lowest value the value axis shows, instead of the data's lowest. Values below it are drawn outside the drawing area.

high? number

The highest value the value axis shows, instead of the data's highest. Values above it are drawn outside the drawing area.

referenceValue? number

A value the value axis always includes, such as 0, so it shows even when all values are above or below it. Bar charts use 0.

chartPadding? number | Partial<ChartPadding> default { top: 5, right: 5, bottom: 5, left: 5 }

Space in px between the chart's edges and its drawing area (labels sit in it): one number for every side, or an object with some sides.

viewBox? ViewBox

A viewBox for the SVG, so the drawing scales with its box instead of being drawn for its size. Text scales too: adjust it with responsive options.

viewBox.width number

The viewBox width, in SVG units.

viewBox.height number

The viewBox height, in SVG units.

readonly plugins? readonly PluginEntry[]

v2 plugins; convert 1.x plugins with fromLegacyPlugin.

readonly on? PhaseListeners

Phase listeners by phase name (or '*' for all phases), as on in the config of chart(). They're registered before the first render, so they see it too.

on.*? AllPhasesListener

Listens to every phase, with the phase name as first argument.

Parameters

data BarChartData

options? BarChartPresetOptions = {}

Parameters

data LineChartData

options? LineChartPresetOptions = {}

Example

import { lineChartConfig, renderToString, toScene } from 'chartist';

const config = lineChartConfig(
  { labels: ['Mon', 'Tue', 'Wed'], series: [[5, 2, 4]] },
  { showArea: true }
);
export const svg = renderToString(
  toScene(config, { width: 600, height: 300 })
);

Parameters

data PieChartData

options? PieChartPresetOptions = {}

Properties

readonly kind TKind

Which preset: line, bar or pie.

readonly options TOptions

The current options: the given ones over the defaults, with the matching responsive options applied.

readonly data TData

The current data.

update (data?: TData, options?: TOptions, override?: boolean) => void

Changes the data, the options or both and redraws, as 1.x update(): the options extend the current ones, or with override, the defaults.

detach () => void

Stops the chart's responsive updates, as 1.x detach().

Properties

readonly kind TKind

Which preset: line, bar or pie.

readonly options TOptions

The current options: the given ones over the defaults, with the matching responsive options applied.

readonly data TData

The current data.

update (data?: TData, options?: TOptions, override?: boolean) => void

Changes the data, the options or both and redraws, as 1.x update(): the options extend the current ones, or with override, the defaults.

detach () => void

Stops the chart's responsive updates, as 1.x detach().

Properties

readonly kind TKind

Which preset: line, bar or pie.

readonly options TOptions

The current options: the given ones over the defaults, with the matching responsive options applied.

readonly data TData

The current data.

update (data?: TData, options?: TOptions, override?: boolean) => void

Changes the data, the options or both and redraws, as 1.x update(): the options extend the current ones, or with override, the defaults.

detach () => void

Stops the chart's responsive updates, as 1.x detach().

Properties

readonly kind TKind

Which preset: line, bar or pie.

readonly options TOptions

The current options: the given ones over the defaults, with the matching responsive options applied.

readonly data TData

The current data.

update (data?: TData, options?: TOptions, override?: boolean) => void

Changes the data, the options or both and redraws, as 1.x update(): the options extend the current ones, or with override, the defaults.

detach () => void

Stops the chart's responsive updates, as 1.x detach().

Properties

readonly container? Element

The element the chart renders into (undefined in toScene).

update (config: Partial<Omit<ChartConfig, 'plugins' | 'on'>>) => this

Shallow-merges the changes into the config and renders again. Plugins and listeners stay; plugins and on can't change.

detach () => this

Stops reacting to container size changes (and media queries in presets). The output and the listeners stay.

destroy () => void

Detaches, removes the output and clears all listeners.

emit <K extends CustomEventName>(name: K, payload: ChartEvents[K]) => void

Emits a custom event (declared in ChartEvents), e.g. from a plugin. Phase names are reserved: emitting one throws.

on <K extends keyof PhaseEvents>(name: K, listener: PhaseListener<K>) => this

Listens to a phase event, which fires on every render. Listeners of resolve to scene may return a new payload to change what's drawn; compose listeners may return null to drop a node.

off <K extends keyof PhaseEvents>(name: K, listener?: PhaseListener<K>) => this

Removes a phase listener, whoever added it. Without a listener, removes the listeners of the phase added through on and the config's on; plugins keep theirs.

setOptions (options: Omit<TOptions, 'plugins' | 'on'>, how?: { readonly replace?: boolean }) => this

Changes the options and redraws: they extend the current options, or with { replace: true }, the defaults, dropping the options given before. Matching responsive options still apply on top. plugins and on can't change. Coming from 1.x, setOptions(options) is update(undefined, options, true) and setOptions(options, { replace: true }) is update(undefined, options).

Example

import { lineChart } from 'chartist';

const chart = lineChart('#chart', { series: [[1, 3, 2, 5]] });

// Areas from now on; the other options stay.
chart.setOptions({ showArea: true });

Properties

low? number

The lowest value this axis shows, instead of the data's lowest.

high? number

The highest value this axis shows, instead of the data's highest.

referenceValue? number

A value this axis always includes, such as 0.

offset? number

Room in px for the axis labels, between the drawing area and the chart's edge.

position? 'end' | 'start'

Where the labels go: start (left or top) or end (right or bottom).

labelOffset? { x: number; y: number }

Moves the labels by x and y px from where they'd go.

showLabel? boolean

Draws the axis labels.

showGrid? boolean

Draws the grid lines of the axis.

labelInterpolationFnc? (value: Label, index: number) => Label | null | undefined

Turns each label (and its index) into the text to show. Return null or undefined to leave a label out.

scaleMinSpace? number

The minimum space in px between two grid lines of a scale: the scale takes fewer, larger steps to keep it.

onlyInteger? boolean

Only whole numbers on the scale.

ticks? Label[]

The ticks: the labels of a step axis, or the values of a fixed scale axis.

stretch? boolean

Step axis: spreads the ticks over the whole axis, so the last one lands on its end (line charts with fullWidth set it).

divisor? number

Fixed scale axis without ticks: the number of equal steps between its low and high, with a tick at each end.

highLow? { high: number; low: number }

The value range of a scale as { high, low }, instead of the one computed from the data.

readonly type? AxisSetup['type']

A v2 axis factory or a 1.x axis class.