# Scales and axes (Chartist API) > Axes that turn values into positions: step, auto-scaled and fixed, placed on any side. ## cartesianAxes *experimental* ```ts function cartesianAxes(input: readonly AxisDefinition[] | AxesConfig, extra?: Pick): CartesianAxes ``` Creates the axes for the `axes` option of [`chart`](https://chartist.dev/api/chart/#chart): a list of axes, each with an `id`, a `side` and a `type`, several per side if needed. Axis types are v2 factories ([`stepAxis`](https://chartist.dev/api/scales/#stepAxis), [`autoScaleAxis`](https://chartist.dev/api/scales/#autoScaleAxis), [`fixedScaleAxis`](https://chartist.dev/api/scales/#fixedScaleAxis)) or 1.x axis classes; the other fields are the 1.x axis options (`offset`, `low`, `high`, `ticks`, …). Layers pick their axes by id, and each axis scales to the series of the layers drawn on it. Offsets default to 30 px for X axes and 40 px for Y axes, and axes on the same side stack outward in list order. Unknown or duplicate ids throw. The 1.x-style `{ x, y }` form also works, with the same defaults: X at the bottom unless its `position` is `'start'`, Y on the left unless it's `'end'`. Parameters: - `input: readonly AxisDefinition[] | AxesConfig` The axes: a list of [`AxisDefinition`](https://chartist.dev/api/scales/#AxisDefinition)s, or the 1.x `{ x, y }` form. - `extra?: Pick` `reverseData` and `normalize`, for the list form (the `{ x, y }` form takes them inline). ```ts 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' }); ``` ## stepAxis *experimental* ```ts function stepAxis(): AxisFactory ``` Creates a step axis: evenly spaced ticks, one per step, that place values by their index rather than by their value. It's the label axis of line and bar charts. Same rules as 1.x `StepAxis`. Its ticks are the data's `labels`, or the axis's `ticks` when you give them. With `stretch`, the last tick sits at the axis end. ```ts 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()] }); ``` ## autoScaleAxis *experimental* ```ts function autoScaleAxis(): AxisFactory ``` Creates an auto-scaled axis: a scale fitted to the data, with round ticks at least `scaleMinSpace` px apart. Set `low`, `high` or `referenceValue` to widen it, and `onlyInteger` for whole-number steps. Same rules as 1.x `AutoScaleAxis`. It's the value axis of line and bar charts. As an X axis, it places `{ x, y }` values at their real distances. ```ts 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()] }); ``` ## fixedScaleAxis *experimental* ```ts function fixedScaleAxis(): AxisFactory ``` Creates a fixed-scale axis: a scale from `low` to `high` (by default the smallest and largest value) with the `ticks` you give. Without `ticks`, `divisor` splits the range into equal parts with a tick at each end, so `divisor: 4` makes 5 ticks from `low` to `high` (1.x left out the one at `high`). ```ts 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()] }); ``` ## AxisDimension ```ts type AxisDimension = 'x' | 'y' ``` Which way an axis runs: `x` (horizontal) or `y` (vertical). ## AxisSide ```ts type AxisSide = 'top' | 'bottom' | 'left' | 'right' ``` Where an axis sits: `top`/`bottom` are X axes, `left`/`right` Y axes. ## AxisContext ```ts interface AxisContext ``` What an [`AxisFactory`](https://chartist.dev/api/scales/#AxisFactory) gets to create an axis: its direction, the data, the chart area and the axis options. Properties: - `dimension: AxisDimension` Which way the axis runs: `x` or `y`, from its side. - `series: NormalizedSeries[]` Normalized multi-value series (`{ x, y }` values): the series bound to the axis, or all of them. - `labels: readonly Label[]` Normalized labels, padded to the longest series. - `area: Area` The chart area in px, with the offsets of all axes reserved. - `options: AxisOptions` The options of the axis definition, without `id`, `side` and `type`. - `extent?: AxisExtent` The range the layers drawn on the axis need beyond their values, such as the sums of stacked bars (see [`Layer.extent`](https://chartist.dev/api/layers/#Layer.extent)). Scale axes include it in the range they fit to the data; their own `low` and `high` still win. ## AxisExtent *experimental* ```ts interface AxisExtent ``` A range of values on an axis, from `low` to `high`: what a layer reports in [`Layer.extent`](https://chartist.dev/api/layers/#Layer.extent). Properties: - `low: number` The lowest value. - `high: number` The highest value. ## ScaleAxis *experimental* ```ts interface ScaleAxis ``` A positioned axis: ticks, range and projection into px along the axis. An [`AxisFactory`](https://chartist.dev/api/scales/#AxisFactory) creates it once the chart area is known; layers read it to place what they draw. Properties: - `dimension: AxisDimension` Which way the axis runs: `x` or `y`. - `kind: string` The axis type, e.g. `step`, `autoScale`, `fixedScale`. - `stretch?: boolean` Step axes: whether the last tick sits at the axis end. - `step?: number` Step axes: the distance between two ticks in px. - `ticks: readonly Label[]` The values at which grid lines and labels are drawn: labels on a step axis, numbers on a scale. - `range?: { … }` The values at the axis start (`min`) and end (`max`). Step axes have none. - `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. ## AxisFactory *experimental* ```ts interface AxisFactory ``` An axis type: creates the axis once the chart area and data are known. [`stepAxis`](https://chartist.dev/api/scales/#stepAxis), [`autoScaleAxis`](https://chartist.dev/api/scales/#autoScaleAxis) and [`fixedScaleAxis`](https://chartist.dev/api/scales/#fixedScaleAxis) return one; write your own for a scale they don't cover. It goes in the `type` of an axis. Properties: - `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. ## LegacyAxisClass ```ts type LegacyAxisClass = (...args: any[]) => unknown ``` A 1.x axis class (or a custom subclass of the 1.x `Axis`). ## AxisSetup ```ts interface AxisSetup extends Omit ``` An axis's setup: an axis type plus the 1.x axis options (`offset`, `low`, `high`, `ticks`, `showGrid`, …). 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?: { … }` 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?: { … }` The value range of a scale as `{ high, low }`, instead of the one computed from the data. - `type: LegacyAxisClass | AxisFactory` A v2 axis factory, or a 1.x axis class. ## AxisDefinition *experimental* ```ts interface AxisDefinition extends AxisSetup ``` An axis of a composed chart, in the list form of [`cartesianAxes`](https://chartist.dev/api/scales/#cartesianAxes): an id that layers bind to, a side, a type and the 1.x axis options. 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?: { … }` 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?: { … }` The value range of a scale as `{ high, low }`, instead of the one computed from the data. - `type: LegacyAxisClass | AxisFactory` A v2 axis factory, or a 1.x axis class. - `id: string` Names the axis, for the `x` and `y` of layers and the `axes` of [`axisGrid`](https://chartist.dev/api/layers/#axisGrid) and [`axisLabels`](https://chartist.dev/api/layers/#axisLabels). Ids must be unique. - `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. ## AxesConfig ```ts interface AxesConfig ``` The config of [`cartesianAxes`](https://chartist.dev/api/scales/#cartesianAxes): one X and one Y axis in the 1.x form, or a list of axes, plus how the data is read. Properties: - `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. - `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. - `axes?: readonly AxisDefinition[]` The axis list form; used instead of `x`/`y`. - `reverseData?: boolean` Reverse labels and series before projecting (1.x `reverseData`). - `normalize?: { … }` 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. ## PlacedScaleAxis ```ts interface PlacedScaleAxis extends ScaleAxis ``` A created axis with its place in the chart: what the axis layers draw, and what a layer finds in `axes.all`. Properties: - `dimension: AxisDimension` Which way the axis runs: `x` or `y`. - `kind: string` The axis type, e.g. `step`, `autoScale`, `fixedScale`. - `stretch?: boolean` Step axes: whether the last tick sits at the axis end. - `step?: number` Step axes: the distance between two ticks in px. - `ticks: readonly Label[]` The values at which grid lines and labels are drawn: labels on a step axis, numbers on a scale. - `range?: { … }` The values at the axis start (`min`) and end (`max`). Step axes have none. - `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. - `id: string` The axis id: from its definition, or `x` and `y` in the 1.x form. - `side: AxisSide` The side the axis sits on. - `inset: number` Distance in px from the chart area to this axis's band (stacking). - `options: Omit` The axis options (offset, labels, grid), without the type. ## ChartAxes ```ts interface ChartAxes ``` The axes of a laid-out chart. Properties: - `x?: ScaleAxis` The X axis (for layers: the bound one; for the chart: the first). - `y?: ScaleAxis` The Y axis (for layers: the bound one; for the chart: the first). - `all?: readonly PlacedScaleAxis[]` All axes of the chart, in declaration order. ## CartesianAxes *experimental* ```ts interface CartesianAxes ``` Axes for a chart's `axes` option, created by [`cartesianAxes`](https://chartist.dev/api/scales/#cartesianAxes). The pipeline asks them for the chart area and, after `layout`, to create the axes. Charts without axes don't bundle any of this. Properties: - `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. - `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`](https://chartist.dev/api/layers/#Layer.extent)). ## LabelAlign *experimental* ```ts interface LabelAlign ``` How an SVG text label sits in its label box, as set in the `align` option of [`axisLabels`](https://chartist.dev/api/layers/#axisLabels). Properties: - `horizontal: 'end' | 'start' | 'middle'` Aligns the text to the box's left (`start`), center or right (`end`). - `vertical: 'top' | 'bottom' | 'middle'` Aligns the lines of text to the box's top, middle or bottom.