Axes and scales

An axis decides where a value lands. The line and bar charts come with sensible axes, and they cover a lot. When they don’t, you swap an axis type or tune its options: plot values along X too, fix the ticks you care about, or keep the scale to whole numbers.

Three kinds of axes

Chartist has three axis types, each created by a function:

Type	Places a value by	Ticks
`stepAxis()`	Its index: first, second, third…	One per step: the data’s `labels`, or the `ticks` you give
`autoScaleAxis()`	Its value, on a scale fitted to the data	Round numbers, at least `scaleMinSpace` px apart (default 20)
`fixedScaleAxis()`	Its value, between `low` and `high`	The `ticks` you give, or `divisor` evenly spaced ones

A step axis doesn’t look at values at all, which is right for categories like weekdays or quarters. The two scale axes are continuous: a value of 7 lands at 70% of an axis from 0 to 10.

How the presets choose

Preset	X axis	Y axis
`lineChart()`	A step axis over `labels`; `fullWidth: true` stretches it	An auto scale
`barChart()`	A step axis over `labels`	An auto scale that includes zero, unless you set `low` or `high`, on the chart or the axis
`pieChart()`	None: a pie has no axes

With horizontalBars: true, the bar chart swaps them: the labels go down the Y axis and the values along X.

The labels in your data only become ticks through that default step axis. Give axisX another type and the labels have nothing left to do.

Tuning the auto scale

The auto scale fits the data and picks round steps. These axis options steer it:

Option	What it does
`low`, `high`	The range of the scale; an auto scale rounds its ends out to a step, `fixedScaleAxis()` keeps them
`onlyInteger`	Steps of whole numbers only
`scaleMinSpace`	The smallest distance between two ticks in px; larger values give fewer ticks
`referenceValue`	A value the scale includes, like a zero line; `low` and `high` win over it

Small counts are where onlyInteger shines. Without it, this chart would put ticks between the whole numbers:

src/main.ts

import 'chartist/styles.css';
import { lineChart } from 'chartist';

// Bugs found per day: nobody finds half a bug.
lineChart(
  '#chart',
  {
    labels: ['Mon', 'Tue', 'Wed', 'Thu', 'Fri'],
    series: [[2, 3, 1, 4, 2]]
  },
  {
    axisY: {
      onlyInteger: true,
      low: 0
    }
  }
);

Live

Label text

Every axis takes a labelInterpolationFnc. It gets each tick’s value and index and returns the label to show. Return null and the tick is skipped, label and grid line both:

import 'chartist/styles.css';
import { lineChart } from 'chartist';

const days = Array.from({ length: 30 }, (_, i) => i + 1);

lineChart(
  '#chart',
  {
    labels: days,
    series: [days.map(day => Math.round(12 + 6 * Math.sin(day / 4)))]
  },
  {
    axisX: {
      // A label every five days.
      labelInterpolationFnc: (value, index) =>
        index % 5 === 0 ? `Day ${value}` : null
    },
    axisY: {
      labelInterpolationFnc: value => `${value} °C`
    }
  }
);

To keep a grid line but hide its label, return an empty string instead.

A line chart is only 1-dimensional?!

A step axis places values by index, so a plain series is all it needs. Under the hood, Chartist turns every value into a point with an empty x:

[5, 2, 8];
// becomes
[
  { x: undefined, y: 5 },
  { x: undefined, y: 2 },
  { x: undefined, y: 8 }
];

Which means you can fill in x yourself. Give the series { x, y } points and the X axis a scale type, and the line chart becomes an XY plot. You don’t need labels anymore:

import 'chartist/styles.css';
import { autoScaleAxis, lineChart } from 'chartist';

lineChart(
  '#chart',
  {
    series: [
      [
        { x: 1, y: 2 },
        { x: 2.5, y: 5 },
        { x: 7, y: 3 },
        { x: 10, y: 8 }
      ]
    ]
  },
  {
    axisX: { type: autoScaleAxis(), onlyInteger: true }
  }
);

The points now sit at their real distances: the gap between 2.5 and 7 is three times the gap between 1 and 2.5, as it should be.

Fixed stuff can be sweet too!

Sometimes you know which ticks matter. fixedScaleAxis() puts the scale between low and high and draws exactly the ticks you give it. Here it gives a day its four quarters, with temperature readings taken at odd hours. showLine: false turns the line chart into a scatter plot:

src/main.ts

import 'chartist/styles.css';
import { fixedScaleAxis, lineChart } from 'chartist';

// Temperature readings, taken whenever someone remembered to.
lineChart(
  '#chart',
  {
    series: [
      [
        { x: 1, y: 9 },
        { x: 4, y: 7 },
        { x: 7, y: 8 },
        { x: 8, y: 11 },
        { x: 9, y: 13 },
        { x: 12, y: 18 },
        { x: 15, y: 21 },
        { x: 16, y: 20 },
        { x: 20, y: 15 },
        { x: 23, y: 11 }
      ]
    ]
  },
  {
    showLine: false,
    axisX: {
      type: fixedScaleAxis(),
      low: 0,
      high: 24,
      ticks: [0, 6, 12, 18, 24]
    }
  }
);

Live

Without low and high, the scale runs from the smallest to the largest value in the data. Instead of ticks, you can give a divisor: it splits the range into that many equal parts, with a tick at each end. With low: 0, high: 100 and divisor: 4, the ticks are 0, 25, 50, 75 and 100.

Axes in composed charts

The axis types and options are the same in composed charts, where you list the axes yourself, give them ids and put them on any side.

In the API reference: the axis options and scales and axes.

Next: compose bars and a line on two axes, or animate a chart.