Renderers | Tiptap Diagrams Docs

Quick start

import { Diagrams } from '@tiptap-pro/extension-diagrams'
import { d3Renderer } from '@tiptap-pro/extension-diagrams/d3'
import { echartsRenderer } from '@tiptap-pro/extension-diagrams/echarts'

Diagrams.configure({
  renderers: [echartsRenderer(), d3Renderer()],
  defaultRenderer: 'echarts',
})

The extension bundles no chart library. Each library is a peer dependency or a script you serve, and you use it under its own license.

Which Renderer to use

A chart Renderer draws charts, and you pass it in renderers. A Diagram Renderer draws one or more diagram formats, such as Mermaid or BPMN, and you pass it in diagramRenderers. You can register several of each. A diagram is drawn by the first Diagram Renderer whose draws accepts its source, see Which Renderer draws a diagram.

Renderer	Draws	Use it for
ECharts	Charts: every built-in type	The most chart types, and SVG files on a server
D3	Charts: most types, and sankey with `d3-sankey`	Charts you change in code, and SVG files on a server with a DOM
Mermaid	Charts: pie, line, upright bar, sankey, radar, treemap. Diagrams: every Mermaid kind	The Mermaid look, for charts and diagrams alike
Pele	Diagrams: every Mermaid kind	Mermaid diagrams without an iframe, much smaller to load, also on a server
draw.io	Diagrams: draw.io XML	Diagrams you draw and change in the draw.io editor
BPMN	Diagrams: BPMN 2.0 XML	Process models that BPMN tools read

Which Renderer draws a chart

A chart can name a Renderer by its id, set with setChartRenderer. The extension picks one of the registered chart Renderers in this order:

The Renderer the chart names, if it is registered and draws the chart's type.
Otherwise the defaultRenderer, if it draws the type.
Otherwise the first registered Renderer that draws the type.

The chart's root element names the Renderer that drew it in data-tt-chart-renderer.

When a Renderer declines a chart

A Renderer can decline a chart of a type it draws. For example, the Mermaid Renderer declines a bar chart with several series.

Another Renderer draws the type. The next Renderer in the order above draws the chart.
No other Renderer draws the type. The declining Renderer draws the chart after all.
The chart keeps its choice. It still names the Renderer it named before.
An export with a renderer option uses that Renderer as it is, even if it declines.

When no Renderer draws the type

The chart shows what unavailable returns. Its data stays in the document.

When the Renderer changes

Only the drawing changes. The Chart Data and the Chart Spec stay as they are.
Options for one Renderer that a chart stores under spec.renderer[id] are ignored by the other Renderers.
Colors and fonts come from the same --tt-chart-* custom properties for every Renderer. See Styling.

A diagram goes to the first Diagram Renderer for its format that does not decline it. See Which Renderer draws a diagram.

Your own Renderer

A chart Renderer of your own can draw with any library. It receives the Chart Data and the Chart Spec, never the document.

Your own Renderer is a complete chart Renderer, with its members.
A Renderer that draws on a canvas draws a PNG. Every exported file, SVG too, is made from it.
Chart types adds a chart type.
A Diagram Renderer draws a diagram format.

PreviouslyData Sources

Next upECharts