--- title: "Axes" description: "spec.axes holds a chart's axis titles, ranges, grid and axis lines and ticks, and which category labels are written at what angle." canonical_url: "https://tiptap-docs.lin52025i.qzz.io/diagrams/charts/axes" --- # 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. ## Quick start ```ts 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. This stays the same when bars lie on their side. | Field | Axis | Type | Description | | ------------ | ---- | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `title` | Both | `string` | The axis title | | `min`, `max` | Both | `number` | The range of the value axis, and of a scatter chart's x axis when it holds numbers. Without them, the data decides | | `step` | `y` | `number` | The distance between two ticks, and so between two value grid lines. See [Tick step](https://tiptap-docs.lin52025i.qzz.io/diagrams/charts/axes.md#tick-step) | | `grid` | Both | `ChartStroke` | Grid lines across the plot, at each category (`x`) or value (`y`). See [Grid and axis lines](https://tiptap-docs.lin52025i.qzz.io/diagrams/charts/axes.md#grid-and-axis-lines) | | `line` | Both | `ChartStroke` | The axis line itself | | `labels` | `x` | `CategoryLabels` | Which category labels are written and how far they are turned. See [Category labels](https://tiptap-docs.lin52025i.qzz.io/diagrams/charts/axes.md#category-labels) | ## Grid and axis lines `grid` and `line` are each a `ChartStroke`, an object that says how one line is drawn: | Field | Type | Description | | ------- | ------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | | `line` | `'none' \| 'solid' \| 'dashed' \| 'dotted'` | How the line is drawn. `'none'` leaves it out | | `width` | `number` | 0.5 to 4 CSS pixels. Default 1 | | `color` | `string` | A CSS color. Without it, the theme's grid or axis color | | `every` | `number` | Category grid only, see [Grid lines at some categories](https://tiptap-docs.lin52025i.qzz.io/diagrams/charts/axes.md#grid-lines-at-some-categories) | | `at` | `number[]` | Category grid only, see [Grid lines at some categories](https://tiptap-docs.lin52025i.qzz.io/diagrams/charts/axes.md#grid-lines-at-some-categories) | Without `grid` and `line`, a chart has: - grid lines at its values, - no grid lines at its categories, except when the categories are numbers on a scatter chart, - a category axis line, - no value axis line. ### Where a grid line is left out Where a grid line would lie on top of an axis line, only the axis line is drawn. So the value grid has no line where the category axis runs, and the category grid has no line along the value axis. If you hide the category axis with `x.line: { line: 'none' }`, the bottom of the chart has no line at all. When values go below 0, the category axis runs through the plot at 0. The value grid then 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` draws a line at every third category, starting with the first | | `at` | `at: [1, 4, 5]` draws lines only at those categories, counted from 0. Wins over `every` | On a bar chart, the category grid lines run along the edges of the bars, so there is one line more than there are categories. For `every` and `at`, the line at the right edge of the last bar counts as the next category. With 4 bars, it is number 4. The value grid takes neither field. A scatter chart with numbers on its x axis takes neither. ```ts editor.commands.updateChartAxis({ axis: 'y', changes: { grid: { line: 'dotted', color: '#94a3b8' } }, }) editor.commands.updateChartAxis({ axis: 'x', changes: { grid: { line: 'solid', width: 0.5 } } }) editor.commands.updateChartAxis({ axis: 'x', changes: { grid: { line: 'solid', every: 3 } } }) ``` ## Category labels `x.labels` is a `CategoryLabels` object. It leaves out or turns category labels, for long labels on a narrow chart. `every` and `at` pick categories as they do for [grid lines](https://tiptap-docs.lin52025i.qzz.io/diagrams/charts/axes.md#grid-lines-at-some-categories). | Field | Type | Description | | ------- | ---------- | ----------------------------------------------------------------- | | `every` | `number` | `{ every: 2 }` writes every second label, starting with the first | | `at` | `number[]` | `{ at: [0, 5, 11] }` writes only those, counted from 0 | | `angle` | `number` | Turns the labels counterclockwise, from -90 to 90 degrees | - Only labels are left out. The categories, their bars and their points stay. - At `angle: 45`, a label rises to the right and ends at its category, so long names fit side by side. - Without `every` or `at`, labels that would overlap are left out. ```ts editor.commands.updateChartAxis({ axis: 'x', changes: { labels: { every: 3 } } }) ``` ## 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. Both are drawn by default. The [ECharts](https://tiptap-docs.lin52025i.qzz.io/diagrams/renderers/echarts.md#chart-types) and [D3](https://tiptap-docs.lin52025i.qzz.io/diagrams/renderers/d3.md#chart-types) Renderers draw every field. The Mermaid Renderer declines a chart that sets them, see its [limits](https://tiptap-docs.lin52025i.qzz.io/diagrams/renderers/mermaid.md#limits). A Renderer of your own can draw the axes as the built-in ones do, see [What to honor in the spec](https://tiptap-docs.lin52025i.qzz.io/diagrams/renderers/custom.md#what-to-honor-in-the-spec). ### In a Word document Word draws what the spec sets, and `every`, but not `at`. - A color is used when it is a `#rrggbb` value. Otherwise Word uses the theme's color. - A category axis line set to `'none'` keeps the grid line along it. - `step` becomes the major unit of the value axis. - `labels.every` becomes the label skip. - `labels.angle` becomes the rotation of the labels. - `labels.at` has no equivalent in Word, so Word writes every label. ## Commands ### updateChartAxis Changes fields of `spec.axes.x` or `spec.axes.y` and keeps the rest. A field set to `undefined` is removed. ```ts editor.commands.updateChartAxis({ axis: 'y', changes: { title: 'EUR', min: 0 } }) ``` | Option | Type | Description | | --------- | -------------------- | ----------------------------------------------------------------------------------------------------------------- | | `axis` | `'x' \| 'y'` | The category axis (`x`) or the value axis (`y`) | | `changes` | `Partial` | The fields to change, see [Axis fields](https://tiptap-docs.lin52025i.qzz.io/diagrams/charts/axes.md#axis-fields) | | `pos` | `number` | The chart's position. Defaults to the selected chart | Returns `false` when there is no chart at `pos`, or no chart is selected.