Appearance | Tiptap Diagrams Docs

Quick start

editor.commands.updateChartSpec({ spec: { title: 'Revenue', border: true, caption: true } })

Framing fields

Besides type, title, legend, palette and axes, the spec holds how the chart is framed:

Field	Type	Description
`description`	`string`	Alt text and accessible description
`caption`	`boolean`	`true` shows the description as a visible caption below the chart
`background`	`string`	A solid CSS color behind the chart: a hex, `rgb()`, `hsl()` or named color. Anything else is dropped
`border`	`boolean`	`true` frames the chart in `--tt-chart-border-color`
`hidden`	`boolean`	`true` while only the table the chart follows is shown. Set by `setChartLayout`, dropped when that table is gone
`size`	`FigureSize`	`{ width, ratio, locked }`, see `setDiagramSize`
`series`	`Record<string, SeriesStyle>`	Line styles of a line or area chart, by column id. See Series line styles
`style`	`string`	A style by id, such as `'ocean'`; see Styles
`encoding`	`ChartEncoding`	`{ label?, series?, seriesIn? }`: which columns are drawn. See Which columns are drawn

palette, background and border override the style.
An unknown style id is ignored.

Horizontal bars

spec.orientation: 'horizontal' lays the bars of a bar or combo chart on their side, with the categories down the left. Without it, or with 'vertical', bars stand upright.

editor.commands.updateChartSpec({ spec: { orientation: 'horizontal' } })

Renderer	Bar	Combo
ECharts	On their side	On their side
d3	On their side	Upright
Mermaid	Declined: another registered Renderer draws it	Not drawn by Mermaid

Other chart types ignore it, so it may stay in the spec when the type changes.
Long category names read better on their side than turned at an angle.

Series line styles

Give each line its own stroke, width, markers and curve:

New tab

spec.series sets how a series of a line or area chart is drawn: { [columnId]: { line?, width?, marker?, smooth? } }. 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`	The stroke width in CSS pixels, 0.5 to 8. Default 2
`marker`	`'none'`, `'circle'` or `'square'` at each value
`smooth`	`true` draws a curve through the values

updateChartSpec replaces series as a whole; pass every entry you want to keep.

Renderer	Draws
ECharts	Every field
d3	Every field
Word	All four on a line chart, none on the edges of an area chart
Mermaid	None, so a line chart with `series` goes to another Renderer

Which columns are drawn

encoding holds column ids:

Field	Description
`label`	The column that names the rows
`series`	The columns drawn, in that order
`seriesIn`	`'rows'` swaps rows and columns, see `setChartSeriesIn`

Without encoding, the first column is the label and every number column a series.
The Chart Data keeps every column. encoding only decides what is drawn, in the editor and in every export.
An id that is not in the data is ignored.
A series that names no existing column draws every series.

Where the frame shows

The background reaches every Renderer and every export.
The border and the caption appear in the editor, in HTML, in a Word document and in an SVG or image export.
An SVG or image export frames the chart with the padding, border and caption the editor shows.

Choosing the Renderer

A chart is drawn by one of the registered Renderers, in this order:

The Renderer the chart names (setChartRenderer), if it is registered and draws the chart type.
Otherwise defaultRenderer, if it draws the type.
Otherwise the first registered Renderer that draws the type.

When a Renderer declines a chart

A Renderer can decline a chart of a type it draws, through draws. The Mermaid Renderer declines a bar chart with several series and a line chart with line styles.

Another Renderer draws the type: the next one in the order above draws the chart.
No other Renderer draws the type: the declining Renderer draws it after all.
The chart keeps the Renderer it names.
The chart's root says in data-tt-chart-renderer which Renderer drew it.
export with an explicit renderer option uses that Renderer as it is.

When no Renderer draws the type

The chart shows what unavailable returns and keeps its data.

When the Renderer changes

The picture changes. Data and spec stay as they are.
Options a chart stores for one Renderer under spec.renderer[id] are ignored by the others.
Colors and fonts come from the same --tt-chart-* custom properties for every Renderer, so charts look alike whichever library draws them. See Styling.

Commands

updateChartSpec

Changes fields of the Chart Spec. A field set to undefined is removed.

editor.commands.updateChartSpec({ spec: { title: 'Revenue', stacked: undefined } })

Option	Type	Description
`spec`	`ChartSpecPatch`	The fields to change
`pos`	`number`	The chart's position. Defaults to the selected chart

setChartRenderer

Draws the chart with the Renderer of that id, or with the default for null. Data and spec are not touched.

editor.commands.setChartRenderer({ renderer: 'd3' })

Option	Type	Description
`renderer`	`string \| null`	The id of a registered Renderer, or `null`
`pos`	`number`	The chart's position. Defaults to the selected chart

PreviouslyCharts

Next upLooks