chart()

chart

experimentalSource

function chart(target: string | Element, config: ChartConfig): ChartHandle

Creates a chart from data, axes and layers in a container, and renders it right away. The presets (lineChart, barChart, pieChart) are built on it; use it for what they don't cover, like bars and a line on two Y axes.

The chart fills its container unless the config sets a size, and renders again when the container resizes, web fonts finish loading or the matching responsive entries change. Listeners in config.on and plugins receive the events of the first render too. While the page is printed, the SVG gets a viewBox of its layout size (unless the config sets one), so the drawing scales into the box it gets in the print.

Without className, the SVG gets the chart type class of its layers, so the stylesheet's chart type rules apply: ct-chart-bar if a layer draws bars, else ct-chart-pie or ct-chart-donut for a pie layer, else ct-chart-line. A className replaces it.

Parameters

target string | Element: The container element, or a CSS selector for it.
config ChartConfig: The data, axes, layers and the rest of the chart.

Returns

A handle to update the chart, listen to it or remove it.

Example

import {
  autoScaleAxis,
  axisGrid,
  axisLabels,
  bar,
  cartesianAxes,
  chart,
  line,
  stepAxis
} from 'chartist';

const months = ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun'];

chart('#chart', {
  data: {
    labels: months,
    series: [
      { name: 'rain', data: [64, 58, 70, 82, 104, 120] },
      { name: 'temperature', data: [1, 3, 8, 12, 16, 20] }
    ]
  },
  axes: cartesianAxes([
    { id: 'month', side: 'bottom', type: stepAxis(), ticks: months },
    { id: 'mm', side: 'left', type: autoScaleAxis(), low: 0 },
    { id: 'celsius', side: 'right', type: autoScaleAxis(), low: 0 }
  ]),
  layers: [
    axisGrid({ axes: ['month', 'mm'] }),
    bar({ series: ['rain'], x: 'month', y: 'mm' }),
    line({ series: ['temperature'], y: 'celsius', align: 'center' }),
    axisLabels()
  ]
});

ChartConfig

experimentalSource

interface ChartConfig extends PipelineOptions

The config of chart: the data, the layers that draw it and the axes they draw on, plus size, padding, plugins and listeners.

Without axes, layers draw into the whole chart area; the pie layer needs coordinates: 'polar'. toScene takes the same config.

Properties

readonly plugins? readonly PluginEntry[]: Plugins to install before the first render, in order: plugins, or plugins with their options from withOptions.
readonly on? PhaseListeners: Phase listeners by phase name (or '*' for all phases). They're registered before the first render, so they see it too.
readonly renderer? Renderer<RenderOutput>: Turns the scene into output; the DOM renderer by default.
readonly responsive? ResponsiveSet<Partial<Omit<ChartConfig, 'plugins' | 'responsive' | 'on' | 'renderer'>>>: Overrides that apply while their condition matches, created with responsive([...]): entries of a media query string or a container() condition, and a partial config. The chart renders again when the matching entries change.
readonly data ChartData: The labels and series to draw.
readonly layers readonly Layer[]: What to draw, in this order (later layers on top), e.g. [axisGrid(), line()].
readonly coordinates? Coordinates: The coordinate system the layers draw in: cartesian (the default) for axes, polar for pie().
readonly padding? number | Partial<ChartPadding>: Space in px between the chart's edge and the drawing area: one number for all sides, or some sides (the others keep the 1.x defaults).
readonly axes? CartesianAxes: Axes (see cartesianAxes); their offsets are reserved around the area.
readonly width? string | number: The chart's width: px as a number, or a CSS length such as 100% or 20rem. Without it, chart() fills the container's width.
readonly height? string | number: The chart's height: px as a number, or a CSS length such as 300px. Without it, chart() fills the container's height.
readonly viewBox? { readonly width: number; readonly height: number }: Fixed drawing coordinates; sets the layout size and the root viewBox.
readonly className? string: Class names for the root svg, e.g. ct-chart-line for the 1.x line chart CSS.
readonly labels? LabelMode: Draws labels as HTML in foreignObject (1.x) or as SVG text. The default depends on the renderer: html for the DOM, svg in toScene().
readonly preset? LinePresetState | BarPresetState | PiePresetState: The preset that created the chart, if any (read by plugins).

ChartOverrides

experimentalSource

type ChartOverrides = Partial<Omit<ChartConfig, 'responsive' | 'plugins' | 'on' | 'renderer'>>

The part of a ChartConfig that responsive entries can override: everything but responsive, plugins, on and renderer. The matching entries merge over the config in order, shallowly.

Properties

readonly data? ChartData: The labels and series to draw.
readonly layers? readonly Layer[]: What to draw, in this order (later layers on top), e.g. [axisGrid(), line()].
readonly coordinates? Coordinates: The coordinate system the layers draw in: cartesian (the default) for axes, polar for pie().
readonly padding? number | Partial<ChartPadding>: Space in px between the chart's edge and the drawing area: one number for all sides, or some sides (the others keep the 1.x defaults).
readonly axes? CartesianAxes: Axes (see cartesianAxes); their offsets are reserved around the area.
readonly width? string | number: The chart's width: px as a number, or a CSS length such as 100% or 20rem. Without it, chart() fills the container's width.
readonly height? string | number: The chart's height: px as a number, or a CSS length such as 300px. Without it, chart() fills the container's height.
readonly viewBox? { readonly width: number; readonly height: number }: Fixed drawing coordinates; sets the layout size and the root viewBox.
readonly className? string: Class names for the root svg, e.g. ct-chart-line for the 1.x line chart CSS.
readonly labels? LabelMode: Draws labels as HTML in foreignObject (1.x) or as SVG text. The default depends on the renderer: html for the DOM, svg in toScene().
readonly preset? LinePresetState | BarPresetState | PiePresetState: The preset that created the chart, if any (read by plugins).

ChartHandle

experimentalSource

interface ChartHandle

The handle chart returns: update or remove the chart, and listen to its events. Plugins get the same handle in install. The methods other than destroy and emit return the handle, so calls chain.

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.