Quick start
On a selected chart, as after the Charts quick start:
editor.commands.updateChartSpec({
spec: { title: 'Revenue', description: 'Revenue per month', border: true, caption: true },
})Chart Spec fields
Every field except type is optional. A field that is not valid or not known is dropped:
| Field | Type | Default | Description |
|---|---|---|---|
type | ChartType | Required | See Chart types |
title | string | None | Above the chart. Empty is dropped |
description | string | None | Alt text and accessible description |
caption | boolean | false | true shows the description as a caption below the chart |
legend | { show, position } | { show: true, position: 'bottom' } | position: 'top', 'right', 'bottom' or 'left' |
palette | string[] | The style's, then --tt-chart-series-1 to --tt-chart-series-8 | Series colors, as CSS colors |
background | string | --tt-chart-background | A solid CSS color: hex, rgb(), hsl() or named |
border | boolean | false | true frames the chart in --tt-chart-border-color. Only true is stored |
style | string | None | A registered style by id, such as 'ocean' |
stacked | boolean | false | true stacks bars and areas |
innerRadius | number | 0.55 | A doughnut's hole, 0 to 0.9 of the radius, clamped |
orientation | 'vertical' | 'horizontal' | 'vertical' | See Horizontal bars |
range | { min, max } | { min: 0, max: 100 } | A gauge's scale, kept only when max is greater than min |
series | Record<string, SeriesStyle> | None | See Series line styles |
encoding | { label?, series?, seriesIn? } | Every column | See Which columns are drawn |
axes | { x?: ChartAxis, y?: ChartAxis } | None | See Axes |
references | ChartReference[] | None | See Reference lines and bands |
size | { width, ratio, locked, align? } | Full width at 16:9 | See setDiagramSize |
hidden | boolean | false | Only the table the chart reads shows, see setChartLayout |
renderer | Record<string, Record<string, unknown>> | None | Options per Renderer id, see When the Renderer changes |
palette and background override the colors of a style. The frame of a style that has one,
such as print, cannot be removed, because border: false is not stored. An unknown style is
ignored.
legend: { show: false } hides the legend. A legend without a valid position stands at the
bottom. A color that is not a CSS color, or could load a resource such as url(), is dropped.
Horizontal bars
spec.orientation: 'horizontal' lays the bars of a bar or combo chart on their side, with the
categories down the left:
editor.commands.updateChartSpec({ spec: { orientation: 'horizontal' } })The Mermaid Renderer declines horizontal bars, so another Renderer draws them, see its
limits. Other types ignore orientation, so it can stay
when the type changes.
Series line styles
spec.series gives each series of a line, area or combo chart its own stroke, width, markers and
curve. Try it on a line chart:
Its keys are column ids. A column without an entry keeps the Renderer's default:
editor.commands.updateChartSpec({
spec: { series: { forecast: { line: 'dashed', marker: 'none' } } },
})| Field | Values |
|---|---|
line | 'solid', 'dashed' or 'dotted' |
width | CSS pixels, clamped to 0.5 to 8. Default 2 |
marker | 'none', 'circle' or 'square' |
smooth | true draws a curve |
updateChartSpec replaces series as a whole, so pass every entry you keep. ECharts and D3 draw
every field, and Mermaid declines a line chart with series. Word draws all four on a line chart,
and none on the edges of an area chart.
Which columns are drawn
encoding names the columns a chart draws, by id, while the Chart Data keeps every column. The
Chart Data has columns, each with an id, a header label and a role, 'label' or 'series'.
Each of its rows holds a cell per column: a string, a number or null for a gap.
| Field | Type | Default | Description |
|---|---|---|---|
label | string | The label column | The column whose cells name the rows |
series | string[] | Every series column | The columns drawn, in this order |
seriesIn | 'columns' | 'rows' | 'columns' | 'rows' makes each row a series named by its label, and each column a category |
With the columns month, revenue and costs, this draws only the costs:
editor.commands.updateChartSpec({ spec: { encoding: { series: ['costs'] } } })An id not in the data is passed over, and when no named series is left, all are drawn.
Data has commands for label and seriesIn as well.
Where the frame shows
The background reaches every Renderer and export. The border and caption appear in the editor, in HTML, in Word, and in an SVG or image export, which keeps the editor's padding.
Choosing the Renderer
A Renderer is the adapter to a chart library. The built-in ids are 'echarts', 'd3' and
'mermaid'. setChartRenderer names one for a chart, and changes only the drawing. Without one, or when it cannot draw the chart, the
extension picks one, see
Which Renderer draws a chart.
Commands
updateChartSpec
Changes fields of the Chart Spec, the type too, and keeps the rest. Each field you pass replaces
the old one whole, so pass all of legend or size. A field set to undefined is
removed.
editor.commands.updateChartSpec({ spec: { title: 'Revenue', stacked: undefined } })| Option | Type | Default | Description |
|---|---|---|---|
spec | ChartSpecPatch | Required | The fields to change, each may be undefined |
pos | number | The selected chart | The chart's position |
Returns false when there is no chart at pos, or no chart is selected.
setChartRenderer
Sets the Renderer that draws the chart. null goes back to the default.
editor.commands.setChartRenderer({ renderer: 'd3' })| Option | Type | Default | Description |
|---|---|---|---|
renderer | string | null | Required | A Renderer id, or null. '' is stored as null, and an unregistered id draws as null does |
pos | number | The selected chart | The chart's position |
Returns false when there is no chart at pos, or no chart is selected.