Appearance

The Chart Spec holds a chart's settings, such as its title, legend, colors and frame, apart from its values. updateChartSpec changes them.
New tab

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:

FieldTypeDefaultDescription
typeChartTypeRequiredSee Chart types
titlestringNoneAbove the chart. Empty is dropped
descriptionstringNoneAlt text and accessible description
captionbooleanfalsetrue shows the description as a caption below the chart
legend{ show, position }{ show: true, position: 'bottom' }position: 'top', 'right', 'bottom' or 'left'
palettestring[]The style's, then --tt-chart-series-1 to --tt-chart-series-8Series colors, as CSS colors
backgroundstring--tt-chart-backgroundA solid CSS color: hex, rgb(), hsl() or named
borderbooleanfalsetrue frames the chart in --tt-chart-border-color. Only true is stored
stylestringNoneA registered style by id, such as 'ocean'
stackedbooleanfalsetrue stacks bars and areas
innerRadiusnumber0.55A 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
seriesRecord<string, SeriesStyle>NoneSee Series line styles
encoding{ label?, series?, seriesIn? }Every columnSee Which columns are drawn
axes{ x?: ChartAxis, y?: ChartAxis }NoneSee Axes
referencesChartReference[]NoneSee Reference lines and bands
size{ width, ratio, locked, align? }Full width at 16:9See setDiagramSize
hiddenbooleanfalseOnly the table the chart reads shows, see setChartLayout
rendererRecord<string, Record<string, unknown>>NoneOptions 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:

New tab

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' } } },
})
FieldValues
line'solid', 'dashed' or 'dotted'
widthCSS pixels, clamped to 0.5 to 8. Default 2
marker'none', 'circle' or 'square'
smoothtrue 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.

FieldTypeDefaultDescription
labelstringThe label columnThe column whose cells name the rows
seriesstring[]Every series columnThe 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 } })
OptionTypeDefaultDescription
specChartSpecPatchRequiredThe fields to change, each may be undefined
posnumberThe selected chartThe 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' })
OptionTypeDefaultDescription
rendererstring | nullRequiredA Renderer id, or null. '' is stored as null, and an unregistered id draws as null does
posnumberThe selected chartThe chart's position

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