--- title: "Axes" description: "Titles, ranges, grid and axis lines, the distance between ticks, and which category labels are written and at what angle." canonical_url: "https://tiptap.dev/docs/diagrams/charts/axes" --- # Axes Titles, ranges, grid and axis lines, the distance between ticks, and which category labels are written and 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, also 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 | | `step` | `y` | `number` | The distance between two ticks, and so between two value grid lines. See [Tick step](https://tiptap.dev/docs/diagrams/charts/axes.md#tick-step) | | `grid` | Both | `ChartStroke` | Grid lines across the plot, at each category (`x`) or value (`y`) | | `line` | Both | `ChartStroke` | The axis line itself | | `labels` | `x` | `CategoryLabels` | `{ every?, at?, angle? }`: which category labels are written and how far they are turned. See [Category labels](https://tiptap.dev/docs/diagrams/charts/axes.md#category-labels) | ## Grid and axis lines `grid` and `line` take `{ line?, width?, color? }`: | Field | Values | | ------- | ------------------------------------------------------- | | `line` | `'none'`, `'solid'`, `'dashed'` or `'dotted'` | | `width` | 0.5 to 4 CSS pixels. Default 1 | | `color` | A CSS color. Without it, the theme's grid or axis color | Without `grid` and `line`, a chart has: - grid lines at its values, - no grid lines at its categories, except numbers on a scatter chart, - a category axis line, - no value axis line. `resolveAxisStrokes(spec)` returns the lines as drawn. ### Where a grid line is left out A grid leaves out the line that would lie on the other axis line. That edge belongs to the axis. - **The value grid** has no line where the category axis runs. - **The category grid** has no line along the value axis. - **With `x.line: { line: 'none' }`** the bottom of the chart has no line. - **When values go below 0**, the category axis runs through the plot at 0, and the grid line at the lowest value stays. ### 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` | - **Bars** have one line more than categories, at the right edge of the last bar. - **The value grid** takes neither. - **A scatter chart with numbers on x** 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` thins out the category labels the same way, for long labels on a narrow chart. | Field | Description | | ------- | ----------------------------------------------------------------- | | `every` | `{ every: 2 }` writes every second label, starting with the first | | `at` | `{ at: [0, 5, 11] }` writes only those | | `angle` | Turns the labels counterclockwise, from -90 to 90 degrees | - **The categories, their bars and their points** stay; only labels are left out. - **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 } } }) editor.commands.updateChartAxis({ axis: 'x', changes: { labels: { angle: 45 } } }) ``` ## 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` fix 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. ```ts editor.commands.updateChartAxis({ axis: 'y', changes: { step: 25 } }) ``` ## For a Renderer of your own | Function | Returns | | ---------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | | `valueAxisScale(spec, valueExtent(series, stacked))` | The value axis as the built-in Renderers draw it, with the step and the [reference lines](https://tiptap.dev/docs/diagrams/charts/references.md) | | `resolveAxisStrokes(spec)` | The grid and axis lines as drawn | ## Which charts draw axes - **Line, bar, area, scatter and combo charts** take every field (`hasAxisLines(type)`). - **A radar chart** (`hasRadarLines(type)`): `y.grid` are the rings and `x.line` the spokes. Both are drawn by default. | Renderer | Draws | | -------- | ------------------------------------------------------------------------------------------------------------------------------------------- | | ECharts | Every field | | d3 | Every field | | Word | What the spec sets, and `every`, but not `at`. See [In a Word document](https://tiptap.dev/docs/diagrams/charts/axes.md#in-a-word-document) | | Mermaid | None of them, and has no step. A chart that sets them goes to another Renderer | ### In a Word document - **A color** is used when it is a `#rrggbb` value; otherwise Word uses the theme's. - **A category axis line set to `'none'`** keeps the grid line along it. - **`step`** becomes the value axis' major unit. - **`labels.every`** becomes its label skip. - **`labels.angle`** becomes the labels' rotation. - **`labels.at`** has no form there, and 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.dev/docs/diagrams/charts/axes.md#axis-fields) | | `pos` | `number` | The chart's position. Defaults to the selected chart |