Renderers

A Renderer is the adapter between the extension and one drawing library, such as ECharts or Mermaid. Each Renderer is its own import path, such as @tiptap-pro/extension-diagrams/echarts, so your app loads only the libraries you register.
New tab

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 d3
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. 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.

RendererDrawsUse it for
EChartsEvery built-in chart typeThe most chart types, SVG on a server
D3Most chart types, sankey with d3-sankeyCharts changed in code, SVG on a server with a DOM library
MermaidPie, doughnut, line, vertical bar, sankey, radar, treemap. Every Mermaid diagram kindThe Mermaid look
PeleEvery Mermaid diagram kindMermaid without an iframe, smaller, on a server
draw.iodraw.io XML diagramsEditing in the draw.io editor
BPMNBPMN 2.0 XML diagramsProcess models for BPMN tools

Which Renderer draws a chart

The extension picks a registered chart Renderer for each chart, in this order:

  1. The one the chart names, set with setChartRenderer, if it draws the chart's type.
  2. The defaultRenderer, if it draws the type.
  3. 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: