Events and plugins

Parameters

plugin ChartPlugin<TOptions>

options TOptions

Example

import { lineChart, withOptions, type ChartPlugin } from 'chartist';

const lastPoint: ChartPlugin<{ className: string }> = {
  name: 'last-point',
  install(chart, options) {
    chart.on('compose', current => {
      if (current.role !== 'series') {
        return;
      }
      const last = current.children.at(-1);
      return last && options
        ? current.replace(last, last.addClass(options.className))
        : undefined;
    });
  }
};

lineChart(
  '#chart',
  { series: [[1, 3, 2, 5]] },
  { plugins: [withOptions(lastPoint, { className: 'ct-last' })] }
);

Properties

responsive { readonly previousConfig: ChartConfig; readonly currentConfig: ChartConfig } | { readonly previousOptions: unknown; readonly currentOptions: unknown }

Responsive entries changed which overrides apply: the config before and after (chart()), or the options before and after (presets).

data DataEvent

1.x: the chart's data, before the first render (type: 'initial') and after an update with new data (type: 'update'). Listeners can change it in place. Needs the compat plugin.

optionsChanged OptionsChangedEvent

1.x: the responsive options changed, with the options before and after. Needs the compat plugin.

draw PointDrawEvent | LineDrawEvent | AreaDrawEvent | AxesDrawEvent | BarDrawEvent | SliceDrawEvent | SliceLabelDrawEvent

1.x: an element was drawn: a grid line, label, point, line, area, bar or slice, with its live element. Check type to narrow it. Needs the compat plugin.

created LineChartCreatedEvent | BarChartCreatedEvent | PieChartCreatedEvent

1.x: the chart is drawn and in the DOM, after its draw events, with the svg, the chart area and the axes. Needs the compat plugin.

animationBegin AnimationEvent

1.x: an SMIL animation began, started with animate() on an element of the chart, such as the element of a draw event. Needs the compat plugin.

animationEnd AnimationEvent

1.x: an SMIL animation ended, started with animate() on an element of the chart. Needs the compat plugin.

Properties

readonly name string

Names the plugin. Prefix your custom events with it to keep them apart.

readonly provides? readonly CustomEventName[]

The custom events this plugin emits with chart.emit(), each declared in ChartEvents. They're known before any plugin installs, so another plugin may listen to them.

install (chart: ChartHandle, options?: TOptions) => unknown

Sets the plugin up: runs once, before the first render, with the chart's handle. Listeners registered here stay for every later render, after updates and resizes too, and off(name) without a listener leaves them alone: remove one with its reference.

Return a function to undo what install set up outside the chart, such as a listener on the document: destroy() calls it once, after the chart's output is removed. detach() doesn't.

keyframes? (previous: SceneNode, next: SceneNode, progress: readonly number[]) => Keyframes | undefined

Gives the keyframes of a node's update animation, for nodes that don't move well number by number, such as a path the plugin draws. A renderer that animates updates (smilAnimations() from chartist/live) asks it once per update, never per frame, with the progress points of the chart's easing: 0 is the previous node, 1 the new one, and points beyond them come from an easing that overshoots. Plugins are asked in their order, before the layer that drew the node; the first one that returns keyframes wins.

Example

import { barChart, type ChartPlugin } from 'chartist';

// Bars at or above the limit get the class ct-over.
const threshold = (limit: number): ChartPlugin => ({
  name: 'threshold',
  install(chart) {
    chart.on('compose', current => {
      if (current.role !== 'bar') {
        return;
      }
      const { value } = current.ctx;
      const y =
        typeof value === 'number'
          ? value
          : value && 'y' in value
            ? value.y
            : undefined;
      return y !== undefined && y >= limit
        ? current.addClass('ct-over')
        : undefined;
    });
  }
});

barChart('#chart', { series: [[5, 4, 3, 7]] }, { plugins: [threshold(5)] });

Properties

readonly labels? readonly (string | number | Date)[]

The labels of the values, e.g. for the X axis or the slices.

readonly series readonly unknown[]

The series: arrays of values, series objects with data, or, for a pie, one value per slice.

Properties

readonly name? string

The series' name, from a series object.

readonly className? string

The series' className, from a series object.

readonly meta? unknown

The series' meta, from a series object.

readonly values readonly unknown[]

The series' values, as given.

Properties

readonly labels readonly (string | number | Date)[]

The labels as given, or an empty array.

readonly series readonly PreparedSeries[]

The series, each with its values.

readonly flat? boolean

The input was a flat series (e.g. pie or distributed bar data).

Properties

readonly x1 number

The left edge.

readonly y1 number

The bottom edge.

readonly x2 number

The right edge.

readonly y2 number

The top edge.

readonly width number

The area's width in px.

readonly height number

The area's height in px.

Properties

readonly width number

The chart's width in px (at least the left and right padding).

readonly height number

The chart's height in px (at least the top and bottom padding).

readonly padding ChartPadding

The padding around the drawing area, in px.

readonly area Area

Where the layers draw, inside the padding and the axes.

readonly inset? ChartPadding

The room layers reserved outside the drawing area with Layer.inset, in px per side; padding includes it. Absent when no layer reserved room.

Properties

readonly labels readonly Label[]

The labels, padded with empty strings to the longest series.

readonly series readonly NormalizedSeries[]

The series' values as numbers, { x, y } values or holes, each series padded with holes to the longest one.

Properties

readonly width number

The chart's width in px.

readonly height number

The chart's height in px.

readonly padding ChartPadding

The chart's padding option, in px, without any reserved room.

readonly data PreparedData

The prepared data; only the layer's series when it selects some.

readonly axes readonly AxisDefinition[]

The chart's axis definitions, with their ids, sides and offsets; empty without axes.

readonly coordinates Coordinates

The chart's coordinate system.

readonly layerIndex number

The layer's index in the chart's layers.

readonly labels LabelMode

How label layers draw labels: chart option, else the renderer's.

readonly measureText MeasureText

Measures text with the renderer's metrics (in the browser, with the page's fonts and the chart's classes).

readonly measureStyle? MeasureStyle

Reads computed styles with the renderer. Absent without a DOM.

Properties

readonly data ChartData

The chart's data, as given.

readonly layers readonly Layer[]

The layers, drawn in this order.

readonly coordinates Coordinates

The coordinate system; cartesian unless the config says otherwise.

readonly padding ChartPadding

The padding in px on every side, the 1.x defaults filled in.

readonly axes? CartesianAxes

The chart's axes, from cartesianAxes(), if it has any.

readonly width? string | number

The root svg's width from the config, e.g. 100% or 600.

readonly height? string | number

The root svg's height from the config, e.g. 300px.

readonly viewBox? { readonly width: number; readonly height: number }

Fixed drawing coordinates for the root svg's viewBox, in px.

readonly className? string

Class names of the root svg, e.g. ct-chart-line.

readonly labels? LabelMode

Label mode for all label layers; else the renderer decides.

readonly preset? LinePresetState | BarPresetState | PiePresetState

The preset that created the chart, if any: its kind, options and data. Check kind to narrow it, e.g. config.preset?.kind === 'line'.

Properties

resolve { readonly config: ResolvedConfig }

The config with defaults applied: padding, coordinates, layers, axes.

prepare { readonly data: PreparedData }

The data, each series as { values, name, className, meta }.

layout Layout

The chart's size and the drawing area inside the padding and axes.

compose SceneNode

Each node with a role that a layer draws, children before their parents: series, lines, areas, points, bars, slices, grid lines and labels. Return a changed node, a new one, or null to drop it.

scene { readonly scene: SceneNode }

The whole scene, its root the svg.

render RenderEvent

The renderer has applied the scene: created, replaced or changed the output in place. output is what it returned.

mount RenderEvent & { readonly elementOf: (node: SceneNode) => Element | undefined; readonly animation?: UpdateAnimation }

The output is in the page; touch elements only here. Return a function to undo what the listener did: it runs before the next render changes the output, and on destroy().

Example

import { barChart, type ChartPlugin } from 'chartist';

// Bars at or above the limit get the class ct-over.
const threshold = (limit: number): ChartPlugin => ({
  name: 'threshold',
  install(chart) {
    chart.on('compose', current => {
      if (current.role !== 'bar') {
        return;
      }
      // A number, { x, y } (with an X scale axis) or a hole.
      const { value } = current.ctx;
      const y =
        typeof value === 'number'
          ? value
          : value && 'y' in value
            ? value.y
            : undefined;
      return y !== undefined && y >= limit
        ? current.addClass('ct-over')
        : undefined;
    });
  }
});

barChart(
  '#chart',
  { labels: ['Q1', 'Q2', 'Q3', 'Q4'], series: [[5, 4, 3, 7]] },
  { plugins: [threshold(5)] }
);

Properties

readonly scene SceneNode

The scene the renderer applied.

readonly output RenderOutput

What the renderer returned.

readonly cause RenderCause

Why the chart rendered, e.g. update or resize.

readonly previous? SceneNode

The previous render's scene; absent on the first render and on hydrate.

readonly changes readonly SceneChange[]

What the render did to the output, in document order. When the renderer changed its output in place (liveDomRenderer() from chartist/live), these are its changes; otherwise every node of the previous scene is removed and every node of the new one added. A hydrate render has an add entry for every node, as a first render.

readonly hydration? { readonly repaired: number }

On a hydrate render: how many attributes, classes and texts of the server's markup differed from the scene the browser built, and were set. 0 when the server and the browser drew the same data and options; more means they didn't. Styles, which the markup leaves out, don't count.

Properties

readonly *? AllPhasesListener

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