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:
| Field | Axis | Type | Description |
|---|---|---|---|
title | Both | string | The axis title |
min, max | Both | number | The 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 |
step | y | number | The distance between ticks, see Tick step |
grid | Both | ChartStroke | Grid lines at each category or value, see Grid and axis lines |
line | Both | ChartStroke | The axis line |
labels | x | CategoryLabels | See Category labels |
Grid and axis lines
grid and line are each a ChartStroke, which says how one line is drawn:
| Field | Type | Default | Description |
|---|---|---|---|
line | 'none' | 'solid' | 'dashed' | 'dotted' | As in the next paragraph | 'none' leaves it out |
width | number | 1 | 0.5 to 4 CSS pixels, clamped |
color | string | The theme's grid or axis color | A CSS color |
every | number | 1 | Category grid only, see some categories |
at | number[] | None | Category 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:
| Field | Description |
|---|---|
every | every: 3: a line at every third category from the first. Capped at 10,000 |
at | at: [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:
| Field | Type | Description |
|---|---|---|
every | number | { every: 2 } writes every second label, from the first |
at | number[] | { at: [0, 5, 11] } writes only those, counted from 0 |
angle | number | Turns 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
#94a3b8or#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. stepbecomes Word's major unit,labels.everyits label skip andlabels.anglethe rotation of the labels.athas no equivalent in Word, so Word draws every grid line and label.everyworks.- 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 } })| Option | Type | Default | Description |
|---|---|---|---|
axis | 'x' | 'y' | Required | The category axis (x) or the value axis (y) |
changes | Partial<ChartAxis> | Required | The fields to change |
pos | number | The selected chart | The chart's position |
Returns false when there is no chart at pos, or no chart is selected.