Axes

spec.axes holds a chart's axis titles, ranges, grid and axis lines and ticks, and which category labels are written at what angle. updateChartAxis changes it.
New tab

Quick start

With a chart selected, as after the Charts quick start, this puts a tick at every 25 and turns the category labels:

editor.commands.updateChartAxis({ axis: 'y', changes: { step: 25 } })
editor.commands.updateChartAxis({ axis: 'x', changes: { labels: { angle: 45 } } })

Axis fields

x is the category axis and y the value axis, also when bars lie on their side:

FieldAxisTypeDescription
titleBothstringThe axis title
min, maxBothnumberThe value range. On x, only for a scatter with numeric labels. Default: from zero, or below it for negative values, to the highest value, widened to reach the reference lines
stepynumberThe distance between ticks, see Tick step
gridBothChartStrokeGrid lines at each category or value, see Grid and axis lines
lineBothChartStrokeThe axis line
labelsxCategoryLabelsSee Category labels

Grid and axis lines

grid and line are each a ChartStroke, which says how one line is drawn:

FieldTypeDefaultDescription
line'none' | 'solid' | 'dashed' | 'dotted'As in the next paragraph'none' leaves it out
widthnumber10.5 to 4 CSS pixels, clamped
colorstringThe theme's grid or axis colorA CSS color
everynumber1Category grid only, see some categories
atnumber[]NoneCategory grid only, see some categories

By default, a chart has solid value grid lines and a solid category axis line, but no value axis line. Category grid lines are drawn by default only on a scatter chart whose labels are numbers.

editor.commands.updateChartAxis({
  axis: 'y',
  changes: { grid: { line: 'dotted', color: '#94a3b8' } },
})
editor.commands.updateChartAxis({ axis: 'x', changes: { grid: { line: 'solid', width: 0.5 } } })

Where a grid line is left out

Where a grid line would lie on an axis line, only the axis line is drawn. So hiding the category axis with x.line: { line: 'none' } leaves the bottom of the chart without a line.

When values go below 0, the category axis runs through the plot at 0, and the value grid keeps its line at the lowest value.

Grid lines at some categories

The category grid (x.grid) also takes every and at:

FieldDescription
everyevery: 3: a line at every third category from the first. Capped at 10,000
atat: [1, 4, 5]: lines only there, counted from 0. Wins over every. An index over 10,000 is dropped
editor.commands.updateChartAxis({ axis: 'x', changes: { grid: { line: 'solid', every: 3 } } })

On a bar chart, the category grid runs along the bar edges, so it has one line more than there are categories. The lines are numbered from 0 at the left edge, so with 4 bars the right edge is line 4. The value grid and a numeric scatter x axis take neither field.

Category labels

x.labels is a CategoryLabels object, which leaves out or turns category labels so long labels fit. every and at pick categories as for grid lines:

FieldTypeDescription
everynumber{ every: 2 } writes every second label, from the first
atnumber[]{ at: [0, 5, 11] } writes only those, counted from 0
anglenumberTurns labels counterclockwise, -90 to 90 degrees, rounded
editor.commands.updateChartAxis({ axis: 'x', changes: { labels: { every: 3 } } })

Only labels are left out, never their bars or points. Without every or at, overlapping labels are left out.

At angle: 45, a label rises to the right and ends at its category. ECharts does not turn the labels of horizontal bars, and D3 not those of a numeric x axis.

Tick step

y.step: 25 puts a tick, a label and a value grid line at 0, 25, 50 and so on. Both ends of the axis round out to whole steps, unless min or max fixes them.

A step that would give more than 100 ticks is ignored. On a combo chart with a second axis, the step applies to the left one.

Which charts draw axes

Line, bar, area, scatter and combo charts take every field. A radar chart takes two: y.grid sets the rings and x.line the spokes, and both are drawn by default.

ECharts and D3 draw every field. Mermaid declines a chart that sets grid or axis lines, y.step or x.labels, see its limits. A Renderer of your own can use valueAxisScale and valueExtent, see What to honor in the spec.

In a Word document

Word draws what the spec sets, except:

  • A hex stroke color, such as #94a3b8 or #ccc, is used. For another, Word uses its own, and the export's notes, its list of warnings, say so. A stroke without a color gets the theme's.
  • A category axis line set to 'none' keeps the grid line along it.
  • step becomes Word's major unit, labels.every its label skip and labels.angle the rotation of the labels.
  • at has no equivalent in Word, so Word draws every grid line and label. every works.
  • Word ignores the range of the x axis, and the notes say so.

Commands

updateChartAxis

Changes fields of spec.axes.x or spec.axes.y and keeps the rest. A field set to undefined is removed, and so is an axis left empty. grid, line and labels are each replaced as a whole.

editor.commands.updateChartAxis({ axis: 'y', changes: { title: 'EUR', min: 0 } })
OptionTypeDefaultDescription
axis'x' | 'y'RequiredThe category axis (x) or the value axis (y)
changesPartial<ChartAxis>RequiredThe fields to change
posnumberThe selected chartThe chart's position

Returns false when there is no chart at pos, or no chart is selected.