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 AxesDrawEvent | PointDrawEvent | LineDrawEvent | AreaDrawEvent | 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) => void

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.

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.

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 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 { readonly scene: SceneNode; readonly output: RenderOutput }

The renderer has written the scene; output is what it returned.

mount { readonly scene: SceneNode; readonly output: RenderOutput; readonly elementOf: (node: SceneNode) => Element | undefined }

The rendered SVG is in the page; touch elements only here.

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 *? AllPhasesListener

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