Appearance | Tiptap Diagrams Docs

Quick start

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

Chart Spec fields

Field	Type	Description
`title`	`string`	Written above the chart
`description`	`string`	Alt text and accessible description
`caption`	`boolean`	`true` shows the description as a visible caption below the chart
`legend`	`ChartLegend`	`{ show, position }`. `show` is a `boolean`, `position` is `'top'`, `'right'`, `'bottom'` or `'left'`. Without it, the legend shows at the bottom
`palette`	`string[]`	The series colors of this chart, as CSS colors. Without it, the style's colors, then `--tt-chart-series-1` and the following custom properties
`background`	`string`	A solid CSS color behind the chart, such as a hex, `rgb()`, `hsl()` or named color. Without it, `--tt-chart-background`
`border`	`boolean`	`true` frames the chart in `--tt-chart-border-color`
`style`	`string`	A registered style by id, such as `'ocean'`. See Styles
`stacked`	`boolean`	`true` draws bars and areas on top of each other instead of side by side
`innerRadius`	`number`	The hole of a doughnut, from `0` to `0.9` of the radius. Default `0.55`
`orientation`	`'vertical' \| 'horizontal'`	`'horizontal'` lays the bars on their side. See Horizontal bars
`series`	`Record<string, SeriesStyle>`	Line styles of a line or area chart, by column id. See Series line styles
`encoding`	`ChartEncoding`	`{ label?, series?, seriesIn? }`: which columns are drawn. See Which columns are drawn
`size`	`FigureSize`	`{ width, ratio, locked }`, see `setDiagramSize`
`hidden`	`boolean`	`true` while only the table the chart follows is shown. `setChartLayout` sets it. It is dropped when that table is gone

type and range, the scale of a gauge, are on Charts. axes is on Axes, references on Reference lines and bands. renderer holds options that only one Renderer understands, see When the Renderer changes.

palette, background and border override the style.
An unknown style id is ignored.
A legend without show is shown. A legend without a valid position stands at the bottom.
A color in palette or background that is not a safe CSS color is dropped. A value that could load a resource, such as url(), is never a color.

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' } })

Not every Renderer lays bars on their side. See the chart types of ECharts and D3, and the limits of Mermaid.

Other chart types ignore orientation, so it can stay in the spec when you change the type. Long category names read better on bars that lie on their side than on labels turned at an angle.

Series line styles

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

New tab

spec.series sets how each series of a line or area chart is drawn, by column id: { [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.

The ECharts and D3 Renderers draw every field. The Mermaid Renderer declines a line chart with series, see its limits. 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 their id. The Chart Data keeps every column. See Which columns are drawn.

Where the frame shows

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

Choosing the Renderer

A chart is drawn by one of the registered Renderers. You can name one with setChartRenderer. Otherwise the extension picks one, see Which Renderer draws a chart. Changing the Renderer changes only the drawing, never the Chart Data or the Chart Spec.

Commands

updateChartSpec

Changes fields of the Chart Spec and keeps the rest. 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

A field that is not valid, such as a color that is not one, is dropped. 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	Description
`renderer`	`string \| null`	The id of a registered Renderer, or `null`
`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.

PreviouslyCharts

Next upLooks