Scales and axes

Parameters

input readonly AxisDefinition[] | AxesConfig

The axes: a list of AxisDefinitions, or the 1.x { x, y } form.

extra? Pick<AxesConfig, 'reverseData' | 'normalize'> = {}

reverseData and normalize, for the list form (the { x, y } form takes them inline).

Example

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

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

chart('#chart', {
  data: {
    labels: months,
    series: [
      { name: 'eur', data: [120, 180, 150, 210] },
      { name: 'usd', data: [130, 195, 160, 230] }
    ]
  },
  axes: cartesianAxes([
    { id: 'month', side: 'bottom', type: stepAxis(), ticks: months },
    // Both on the left: 'eur' next to the chart, 'usd' outside it.
    { id: 'eur', side: 'left', type: autoScaleAxis(), low: 0 },
    { id: 'usd', side: 'left', type: autoScaleAxis(), low: 0, offset: 50 }
  ]),
  layers: [
    axisGrid({ axes: ['month', 'eur'] }),
    bar({ series: ['eur'], y: 'eur' }),
    line({ series: ['usd'], y: 'usd', align: 'center' }),
    axisLabels()
  ],
  className: 'ct-chart-bar'
});

Example

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

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

chart('#chart', {
  data: { labels: months, series: [[4, 6, 5, 9]] },
  axes: cartesianAxes([
    // The months as ticks; stretch: the first and last at the edges.
    { id: 'month', side: 'bottom', type: stepAxis(), stretch: true },
    { id: 'value', side: 'left', type: autoScaleAxis() }
  ]),
  layers: [axisGrid(), line(), axisLabels()]
});

Example

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

chart('#chart', {
  data: {
    series: [
      [
        { x: 1, y: 2 },
        { x: 2.5, y: 5 },
        { x: 7, y: 3 },
        { x: 10, y: 8 }
      ]
    ]
  },
  axes: cartesianAxes([
    { id: 'x', side: 'bottom', type: autoScaleAxis(), onlyInteger: true },
    { id: 'y', side: 'left', type: autoScaleAxis(), low: 0 }
  ]),
  layers: [axisGrid(), line(), axisLabels()]
});

Example

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

const teams = ['Red', 'Blue', 'Green'];

chart('#chart', {
  data: { labels: teams, series: [[64, 81, 47]] },
  axes: cartesianAxes([
    { id: 'team', side: 'bottom', type: stepAxis(), ticks: teams },
    // A percentage scale with three grid lines.
    {
      id: 'percent',
      side: 'left',
      type: fixedScaleAxis(),
      ticks: [0, 50, 100],
      low: 0,
      high: 100
    }
  ]),
  layers: [axisGrid(), line({ showLine: false }), axisLabels()]
});

Properties

readonly dimension AxisDimension

Which way the axis runs: x or y, from its side.

readonly series NormalizedSeries[]

Normalized multi-value series ({ x, y } values): the series bound to the axis, or all of them.

readonly labels readonly Label[]

Normalized labels, padded to the longest series.

readonly area Area

The chart area in px, with the offsets of all axes reserved.

readonly options AxisOptions

The options of the axis definition, without id, side and type.

readonly extent? AxisExtent

The range the layers drawn on the axis need beyond their values, such as the sums of stacked bars (see Layer.extent). Scale axes include it in the range they fit to the data; their own low and high still win.

Properties

readonly low number

The lowest value.

readonly high number

The highest value.

Properties

readonly dimension AxisDimension

Which way the axis runs: x or y.

readonly kind string

The axis type, e.g. step, autoScale, fixedScale.

readonly stretch? boolean

Step axes: whether the last tick sits at the axis end.

readonly step? number

Step axes: the distance between two ticks in px.

readonly ticks readonly Label[]

The values at which grid lines and labels are drawn: labels on a step axis, numbers on a scale.

readonly range? { readonly min: number; readonly max: number }

The values at the axis start (min) and end (max). Step axes have none.

readonly length number

Axis length in px.

project (value: string | number | Date | { x: number; y: number } | { x: number } | { y: number } | undefined, index?: number, series?: NormalizedSeries) => number

Places a value on the axis: the distance in px from the axis start (left, or bottom for y). Step axes place by index instead.

Properties

readonly kind string

The axis type, e.g. step. The axis it creates has the same kind; the line and bar layers center on step axes.

create (context: AxisContext) => ScaleAxis

Creates the axis for a chart area and data. Runs on every layout, so after resizes too.

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 LegacyAxisClass | AxisFactory

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

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 LegacyAxisClass | AxisFactory

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

readonly id string

Names the axis, for the x and y of layers and the axes of axisGrid and axisLabels. Ids must be unique.

readonly side AxisSide

Where the axis sits: bottom or top makes an X axis, left or right a Y axis. Axes on the same side stack outward in list order.

Properties

readonly x? AxisSetup

The X axis in the 1.x form: at the bottom, or the top with position: 'start'. Its offset defaults to 30 px.

readonly y? AxisSetup

The Y axis in the 1.x form: on the left, or the right with position: 'end'. Its offset defaults to 40 px.

readonly axes? readonly AxisDefinition[]

The axis list form; used instead of x/y.

readonly reverseData? boolean

Reverse labels and series before projecting (1.x reverseData).

readonly normalize? { readonly multi?: true | AxisDimension; readonly distributed?: boolean }

How values are normalized (1.x normalizeData): multi is true for { x, y } values, or the dimension single values go to; distributed turns a flat series into one series per value.

Properties

readonly dimension AxisDimension

Which way the axis runs: x or y.

readonly kind string

The axis type, e.g. step, autoScale, fixedScale.

readonly stretch? boolean

Step axes: whether the last tick sits at the axis end.

readonly step? number

Step axes: the distance between two ticks in px.

readonly ticks readonly Label[]

The values at which grid lines and labels are drawn: labels on a step axis, numbers on a scale.

readonly range? { readonly min: number; readonly max: number }

The values at the axis start (min) and end (max). Step axes have none.

readonly length number

Axis length in px.

project (value: string | number | Date | { x: number; y: number } | { x: number } | { y: number } | undefined, index?: number, series?: NormalizedSeries) => number

Places a value on the axis: the distance in px from the axis start (left, or bottom for y). Step axes place by index instead.

readonly id string

The axis id: from its definition, or x and y in the 1.x form.

readonly side AxisSide

The side the axis sits on.

readonly inset number

Distance in px from the chart area to this axis's band (stacking).

readonly options Omit<AxisSetup, 'type'>

The axis options (offset, labels, grid), without the type.

Properties

readonly x? ScaleAxis

The X axis (for layers: the bound one; for the chart: the first).

readonly y? ScaleAxis

The Y axis (for layers: the bound one; for the chart: the first).

readonly all? readonly PlacedScaleAxis[]

All axes of the chart, in declaration order.

Properties

readonly config AxesConfig

The config the axes were created from, with the default offsets filled in.

area (width: number, height: number, padding: ChartPadding) => { width: number; height: number; area: Area }

The chart area with the axis offsets reserved.

readonly definitions readonly AxisDefinition[]

The axis definitions, in declaration order.

bind? (layers: readonly Layer[], data: PreparedData) => LayerBinding[]

Each layer's axis ids and series selection, checked against the data. Without it, every layer draws all series on the first X and Y axis.

create (data: PreparedData, area: Area, bindings?: readonly LayerBinding[], layers?: readonly Layer[]) => { axes: ChartAxes; normalized: NormalizedChartData }

The axes for the final chart area, and the data as they see it. With bindings, each axis's range comes only from the series bound to it. With layers, it also covers the extents they report (see Layer.extent).

Properties

readonly horizontal 'end' | 'start' | 'middle'

Aligns the text to the box's left (start), center or right (end).

readonly vertical 'top' | 'bottom' | 'middle'

Aligns the lines of text to the box's top, middle or bottom.