---
title: "Renderers"
description: "A Renderer is the adapter between the extension and one drawing library, such as ECharts or Mermaid."
canonical_url: "https://tiptap-docs.lin52025i.qzz.io/diagrams/renderers/overview"
---

# Renderers

A Renderer is the adapter between the extension and one drawing library, such as ECharts or Mermaid.

## Quick start

```ts
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](https://tiptap-docs.lin52025i.qzz.io/diagrams/renderers/custom-diagrams.md#which-renderer-draws-a-diagram).

| Renderer                                                                      | Draws                                                                                | Use it for                                                                 |
| ----------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ | -------------------------------------------------------------------------- |
| [ECharts](https://tiptap-docs.lin52025i.qzz.io/diagrams/renderers/echarts.md) | Charts: every built-in type                                                          | The most chart types, and SVG files on a server                            |
| [D3](https://tiptap-docs.lin52025i.qzz.io/diagrams/renderers/d3.md)           | Charts: most types, and sankey with `d3-sankey`                                      | Charts you change in code, and SVG files on a server with a DOM            |
| [Mermaid](https://tiptap-docs.lin52025i.qzz.io/diagrams/renderers/mermaid.md) | Charts: pie, line, upright bar, sankey, radar, treemap. Diagrams: every Mermaid kind | The Mermaid look, for charts and diagrams alike                            |
| [Pele](https://tiptap-docs.lin52025i.qzz.io/diagrams/renderers/pele.md)       | Diagrams: every Mermaid kind                                                         | Mermaid diagrams without an iframe, much smaller to load, also on a server |
| [draw.io](https://tiptap-docs.lin52025i.qzz.io/diagrams/renderers/drawio.md)  | Diagrams: draw\.io XML                                                               | Diagrams you draw and change in the draw\.io editor                        |
| [BPMN](https://tiptap-docs.lin52025i.qzz.io/diagrams/renderers/bpmn.md)       | 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`](https://tiptap-docs.lin52025i.qzz.io/diagrams/charts/appearance.md#setchartrenderer). The extension picks one of the
registered chart Renderers in this order:

1. The Renderer the chart names, if it is registered and draws the chart's type.
2. Otherwise the `defaultRenderer`, if it draws the type.
3. 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](https://tiptap-docs.lin52025i.qzz.io/diagrams/renderers/mermaid.md#limits) 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`](https://tiptap-docs.lin52025i.qzz.io/diagrams/api-reference/options.md#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](https://tiptap-docs.lin52025i.qzz.io/diagrams/guides/styling.md).

A diagram goes to the first Diagram Renderer for its format that does not decline it. See
[Which Renderer draws a diagram](https://tiptap-docs.lin52025i.qzz.io/diagrams/renderers/custom-diagrams.md#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](https://tiptap-docs.lin52025i.qzz.io/diagrams/renderers/custom.md) is a complete chart Renderer, with its members.
- [A Renderer that draws on a canvas](https://tiptap-docs.lin52025i.qzz.io/diagrams/renderers/custom-canvas.md) draws a PNG. Every exported file, SVG
  too, is made from it.
- [Chart types](https://tiptap-docs.lin52025i.qzz.io/diagrams/renderers/custom-chart-types.md) adds a chart type.
- [A Diagram Renderer](https://tiptap-docs.lin52025i.qzz.io/diagrams/renderers/custom-diagrams.md) draws a diagram format.