Quick start
Install the libraries, then register their Renderers in the editor of Install Diagrams. Charts are drawn with ECharts unless a chart names D3 and D3 draws its type:
npm install echarts d3import { 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. You install each one yourself, or serve it as a script, and use it under its own license.
Which Renderer to use
Chart Renderers go in renderers, and Diagram Renderers, which draw diagram formats such as
Mermaid or BPMN, in diagramRenderers. You can register several of each. Mermaid has one of each
kind. A diagram goes to the first Diagram Renderer for its format that does not decline it, see
Which Renderer draws a diagram.
| Renderer | Draws | Use it for |
|---|---|---|
| ECharts | Every built-in chart type | The most chart types, SVG on a server |
| D3 | Most chart types, sankey with d3-sankey | Charts changed in code, SVG on a server with a DOM library |
| Mermaid | Pie, doughnut, line, vertical bar, sankey, radar, treemap. Every Mermaid diagram kind | The Mermaid look |
| Pele | Every Mermaid diagram kind | Mermaid without an iframe, smaller, on a server |
| draw.io | draw.io XML diagrams | Editing in the draw.io editor |
| BPMN | BPMN 2.0 XML diagrams | Process models for BPMN tools |
Which Renderer draws a chart
The extension picks a registered chart Renderer for each chart, in this order:
- The one the chart names, set with
setChartRenderer, if it draws the chart's type. - The
defaultRenderer, if it draws the type. - The first registered Renderer that draws the type.
data-tt-chart-renderer on the chart's root element names the Renderer that drew it, if any.
When a Renderer declines a chart
A Renderer can decline a chart of a type it draws, such as the Mermaid Renderer a bar chart of several series. The next Renderer in the order then draws it. When there is none, the declining Renderer draws it after all.
The chart keeps naming its Renderer. An export with a renderer option
draws with that Renderer even if it declines.
When no Renderer draws the type
The chart shows what unavailable returns, with the reason
'no-renderer', and its data stays in the document.
When the Renderer changes
The drawing changes, but the Chart Data and the Chart Spec stay. Options under spec.renderer[id]
are ignored by other Renderers, and colors come from the same --tt-chart-* custom properties,
see Styling.
Code in a document
Text a document stores never runs as code in your page:
- Mermaid, draw.io and BPMN draw in an iframe with
sandbox="allow-scripts"and a Content Security Policy that loads only the library's files. The editor shows the result in an<img>. - Pele draws in a Web Worker, a background script without access to the page.
- D3 code is a customizer registered in your app. A chart stores only its name.
Your own Renderer follows the same rules, see What a Renderer must not do.
Your own Renderer
A Renderer of your own draws with any library, from the Chart Data and the Chart Spec:
- Your own Renderer: a chart Renderer and its members.
- A Renderer that draws on a canvas: every export made from a PNG.
- Register your own chart type.
- A Diagram Renderer of your own.