@chartist-js/essentials API

Everything is exported from @chartist-js/essentials. Types from chartist link to the Chartist API reference, where Rendering covers the scene and the renderers.

axisTitle

Source

function axisTitle(options: AxisTitleOptions): Layer

Names an axis with a title next to its labels, on any side of the chart. The layer reserves the room the title needs, so the drawing area shrinks and the title never overlaps the labels, whatever font size the stylesheet gives it. One layer draws one title; give each axis its own. Titles on the same side stack outward in the order of layers.

The title is an SVG text with the classes ct-axis-title, ct-horizontal or ct-vertical and ct-start or ct-end, styled with --ct-axis-title-color and --ct-axis-title-size from @chartist-js/essentials/styles.css.

Parameters

options AxisTitleOptions

Example

import { lineChart } from 'chartist';
import { axisTitle } from '@chartist-js/essentials';
import 'chartist/styles.css';
import '@chartist-js/essentials/styles.css';

lineChart(
  '#chart',
  { labels: ['Mon', 'Tue', 'Wed'], series: [[12, 9, 7]] },
  {
    layers: {
      above: [
        axisTitle({ axis: 'x', text: 'Day' }),
        axisTitle({ axis: 'y', text: 'Visits' })
      ]
    }
  }
);

logAxis

Source

function logAxis(options?: LogAxisOptions): AxisFactory

Creates a logarithmic axis, for values that span several orders of magnitude: each power of the base (1, 10, 100, … for base 10) is the same distance from the next, so growth by a factor looks the same everywhere. It goes in the type of a preset's axisX or axisY, or of an axis of cartesianAxes().

Without low and high, the range runs from the power at or below the smallest value to the power at or above the largest; the axis's own low and high set it exactly. The ticks are the powers, every second or third when they'd be closer than scaleMinSpace; the axis's ticks replace them. Zero and negative values have no place on a log scale: they don't count towards the range and are drawn at the start of the axis, so a bar for zero has no length. Use null for a gap.

Trend lines on a log axis are fitted to the logarithms of the values, so they're straight on the axis: an exponential trend on a log Y axis.

Parameters

options? LogAxisOptions = {}: The base and whether to draw minor grid lines.

Example

import { lineChart } from 'chartist';
import { logAxis } from '@chartist-js/essentials';

lineChart(
  '#chart',
  {
    labels: ['2019', '2020', '2021', '2022', '2023', '2024'],
    series: [[120, 980, 4100, 36000, 210000, 850000]]
  },
  {
    axisY: {
      type: logAxis({ minorTicks: true }),
      labelTransform: value => value.toLocaleString('en-US')
    }
  }
);

targetLine

Source

function targetLine(options: TargetLineOptions): Layer

Creates a layer that draws a line across the chart area at a constant value on one axis, such as a goal or a limit (line.ct-target-line). On a Y axis the line is horizontal, on an X axis vertical. It can have a label, drawn as SVG text (text.ct-target-label) next to it inside the chart area, and a class, e.g. ct-series-b for a series' color. The axis widens to include the value, unless its own low or high leave it out; a line outside the axis isn't drawn. For several lines, add a layer per line.

Parameters

options TargetLineOptions

Example

import { lineChart } from 'chartist';
import { targetLine } from '@chartist-js/essentials';
import 'chartist/styles.css';
import '@chartist-js/essentials/styles.css';

lineChart(
  '#chart',
  { labels: ['Jan', 'Feb', 'Mar', 'Apr'], series: [[620, 810, 740, 930]] },
  {
    low: 0,
    layers: {
      above: [
        targetLine({ value: 700, label: 'Min' }),
        targetLine({ value: 1000, label: 'Goal', className: 'ct-series-b' })
      ]
    }
  }
);

trendLine

Source

function trendLine(options?: TrendLineOptions): Layer

Creates a layer that draws a trend line for each series: the straight line that fits its values best (least squares), from its smallest to its largest X, as a line.ct-trend-line in a series group (g.ct-series.ct-series-a), so it takes the series' color. On a step axis X is the value's index, on a scale axis the value's x. Holes are skipped, and a series with fewer than two values gets no line. The Y axis widens to include the line's ends. On an axis with a transform, such as a log axis, the line is fitted to the transformed values, so it's straight on that axis: an exponential trend on a log Y axis. Add it next to the line() or bar() layer that draws the values.

Parameters

options? TrendLineOptions = {}

Example

import { lineChart } from 'chartist';
import { trendLine } from '@chartist-js/essentials';
import 'chartist/styles.css';
import '@chartist-js/essentials/styles.css';

lineChart(
  '#chart',
  {
    labels: ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun'],
    series: [{ name: 'sales', data: [620, 810, 740, 930, 880, 1020] }]
  },
  { layers: { above: [trendLine()] } }
);

valueLabels

Source

function valueLabels<R extends ValueLabelRole = ValueLabelRole>(options?: ValueLabelsOptions<R>): Layer

Creates a layer that writes each value next to the point or bar that shows it: above points, past the ends of bars, and in the middle of stacked segments. It draws from where the chart's other layers drew, after stacking, offsets and compose listeners, so add it as an extra layer: layers.above on a preset, anywhere in a composed chart.

The text is the value along the value axis, written with Intl.NumberFormat; format gets the same item as the format of @chartist-js/tooltips. Labels that don't fit their bar, or would leave the chart, move to a place where they fit. They're SVG text, so they render on servers and in the terminal, styled with --ct-value-label-color, --ct-value-label-inside-color and --ct-value-label-size from @chartist-js/essentials/styles.css.

Parameters

options? ValueLabelsOptions<R> = {}

Example

import { barChart } from 'chartist';
import { valueLabels } from '@chartist-js/essentials';
import 'chartist/styles.css';
import '@chartist-js/essentials/styles.css';

barChart(
  '#chart',
  { labels: ['Q1', 'Q2', 'Q3'], series: [[1250, 1830, 1470]] },
  {
    layers: {
      above: [
        valueLabels({ format: item => `${item.value} units` })
      ]
    }
  }
);

AxisTitleOptions

Source

interface AxisTitleOptions

Options of axisTitle.

Properties

readonly axis string: The id of the axis the title names: x or y on the presets, the ids you gave in cartesianAxes() in composed charts.
readonly text string: The title's text; an empty text draws nothing and takes no room.
readonly align? 'start' | 'middle' | 'end': Where along the axis the title sits: at the start (left on X axes, the bottom on Y axes), in the middle or at the end.
readonly flip? boolean: Turns titles of left and right axes to read from top to bottom instead of from bottom to top. Titles of top and bottom axes don't change.
readonly gap? number: Space between the title and the axis labels, in px.
readonly className? string: Extra class names for the title, e.g. ct-series-b for a color.
readonly classNames? { readonly title?: string }: Replaces the default class: title instead of ct-axis-title.

LogAxisOptions

Source

interface LogAxisOptions

Options of logAxis.

Properties

readonly base? number: The base of the logarithm: the ticks are its powers. Any finite number above 1, such as 2 for a scale that doubles; default 10.
readonly minorTicks? boolean: Draws minor grid lines between the ticks, without labels: at 2 to 9 times each power for base 10, or at the powers left out when the ticks skip some. Style them with --ct-grid-minor-*.

TargetLineContext

Source

interface TargetLineContext extends NoSeries

The context of a targetLine node: the line of a targetLine() layer, across the chart area at a value on an axis. Its ends are in px in the SVG.

Properties

readonly axis ScaleAxis: The axis the value is on; axis.dimension is x or y.
readonly value number: The value the line is drawn at.
readonly label? string: The line's label, if it has one.
readonly x1 number: The X of the line's start, in px.
readonly y1 number: The Y of the line's start, in px.
readonly x2 number: The X of the line's end, in px.
readonly y2 number: The Y of the line's end, in px.
readonly seriesIndex? undefined: Always absent: the node belongs to no series.
readonly valueIndex? undefined: Always absent: the node stands for no value.

TargetLabelContext

Source

interface TargetLabelContext extends NoSeries

The context of a targetLabel node: the label of a target line, and where it's anchored, in px in the SVG.

Properties

readonly axis ScaleAxis: The axis of the line's value.
readonly value number: The value of the line.
readonly text string: The label as drawn.
readonly x number: Px from the left edge of the SVG.
readonly y number: Px from the top edge of the SVG.
readonly seriesIndex? undefined: Always absent: the node belongs to no series.
readonly valueIndex? undefined: Always absent: the node stands for no value.

TrendLineContext

Source

interface TrendLineContext

The context of a trendLine node: the line a trendLine() layer fits through a series' values, y = slope * x + intercept in the axes' values (X is the value's index on a step axis). Its ends are in px in the SVG.

Properties

readonly seriesIndex number: The series' index in the chart's data, across layers.
readonly valueIndex? undefined: Always absent: the line stands for the whole series.
readonly slope number: How much the fitted value changes per unit of X. On axes with a transform, such as a log axis, it's in their transformed values: on a base 10 log Y axis, the powers of ten per unit of X.
readonly intercept number: The fitted value at X 0, in transformed values like slope.
readonly correlation? number: How closely the values follow the line: Pearson's correlation coefficient r, from -1 (every value on a falling line) through 0 (no straight trend) to 1 (every value on a rising line). Its square is R², the share of the values' variation the line explains, as spreadsheets show it next to a trendline. It describes the fit, not how reliable it is: with two values it's always 1 or -1. On axes with a transform, it's computed in their transformed values, so it says how straight the values look on the chart. Absent when all values are equal, where it isn't defined.
readonly x1 number: The X of the line's start (the series' smallest X), in px.
readonly y1 number: The Y of the line's start, in px.
readonly x2 number: The X of the line's end (the series' largest X), in px.
readonly y2 number: The Y of the line's end, in px.

TargetLineOptions

Source

interface TargetLineOptions

The options of the targetLine layer: the line's value, its label and class, and the axis it's on. For several lines, add a layer per line.

Properties

readonly value number: The value the line is drawn at, on the layer's axis. On a step axis, the position by index, as for the axis's ticks.
readonly label? string: The text drawn next to the line; no label without it.
readonly className? string: Extra classes for the line and its label, e.g. ct-series-b.
readonly axis? string: The id of the axis the value is on: a Y axis draws a horizontal line, an X axis a vertical one. Default: the first Y axis.
readonly labelPosition? 'start' | 'end': Where the label sits along the line: at the end (right, or top for a vertical line) or the start (left, or bottom).
readonly classNames? { readonly line?: string; readonly label?: string }: Replaces the classes of what the layer draws: line (ct-target-line) and label (ct-target-label).

TrendLineOptions

Source

interface TrendLineOptions

The options of the trendLine layer. Without them, it draws a trend line for every series, on the first X and Y axis.

Properties

readonly series? readonly (string | number)[]: Series to draw a trend line for, by index or name; default: all series.
readonly x? string: The id of the X axis to draw on; default: the first X axis.
readonly y? string: The id of the Y axis to draw on; default: the first Y axis.
readonly align? 'start' | 'center': Where the line's ends sit on a step axis: at the start of their steps, as the points of line(), or at the center, where bars are centered.
readonly classNames? { readonly series?: string; readonly line?: string }: Replaces the classes of what the layer draws: series (ct-series) and line (ct-trend-line).

ValueLabelRole

Source

type ValueLabelRole = 'point' | 'bar'

The roles whose nodes get labels.

PointLabelPosition

Source

type PointLabelPosition = 'above' | 'below' | 'left' | 'right' | 'center'

Where a point's label sits.

BarLabelPosition

Source

type BarLabelPosition = 'end' | 'inside-end' | 'center' | 'inside-base'

Where a bar's label sits, from the bar's base to its value: past its end, inside its end, in its middle or inside its base.

ValueLabelItem

Source

type ValueLabelItem<R extends ValueLabelRole = ValueLabelRole> = { [K in R]: { readonly role: K; readonly seriesIndex: number; readonly valueIndex: number; readonly value: number | { readonly x: number; readonly y: number }; readonly meta: unknown; readonly series: unknown; readonly seriesName?: string; readonly label?: string; readonly context: NodeRoles[K]['ctx'] } }[R]

The value a label is about: what format gets. It has the fields of the item @chartist-js/tooltips gives its format, under the same names, so a function written for one mostly works for the other. Checking item.role narrows item.context to that role's context.

ValueLabelContext

Source

interface ValueLabelContext

The context of a valueLabel node.

Properties

readonly role ValueLabelRole: The role of the node the label is for.
readonly seriesIndex number: The series' index in the chart's data.
readonly valueIndex number: The value's index in its series.
readonly value unknown: The labeled value, as the node has it.
readonly meta unknown: The value's meta.
readonly series unknown: The series as given in the data.
readonly text string: The label's text.
readonly position 'left' | 'right' | 'end' | 'center' | 'above' | 'below' | 'inside-end' | 'inside-base': Where the label ended up, after fitting.
readonly x number: Px from the left edge of the SVG: where the text is anchored.
readonly y number: Px from the top edge of the SVG: the first line's baseline.

ValueLabelsOptions

Source

interface ValueLabelsOptions<R extends ValueLabelRole = ValueLabelRole>

Options of valueLabels.

Properties

readonly roles? readonly R[]: The nodes that get labels: point, bar or both (the default).
readonly series? readonly (string | number)[]: The series to label, by index or name; default: all of them.
readonly pointPosition? PointLabelPosition: Where point labels sit; default above.
readonly barPosition? BarLabelPosition: Where bar labels sit; default end, and center for segments of stacked bars.
readonly offset? number: The gap in px between a point's center, or a bar's end or base, and the label's nearest edge; default 8 for points and 4 for bars.
readonly format? (item: ValueLabelItem<R>) => string | number | null | undefined: The label's text for a value: a string or a number. undefined keeps the default text, null or '' draw no label, and \n starts a new line.
readonly numberFormat? NumberFormatOptions: Intl.NumberFormat options for the default text.
readonly locale? string | readonly string[]: The locale of the default text; default: the runtime's. Set it when charts render on a server, so the text doesn't depend on its locale.
readonly overflow? 'fit' | 'show': fit (the default) moves labels that don't fit their bar or would leave the chart; show draws every label where its position puts it.
readonly labels? 'svg' | 'html': SVG text (the default) or HTML in a foreignObject.
readonly classNames? { readonly group?: string; readonly label?: string; readonly inside?: string }: Replace the classes: group (ct-value-labels), label (ct-value-label) and inside (ct-value-label-inside).