Install Diagrams
Alpha
Diagrams is in alpha and available through a pilot program. The API may change in future releases.
Install
The package is on Tiptap's private registry:
- Contact our team to join the Tiptap Diagrams pilot program.
- Configure your package manager by following the private registry guide.
- Install the package and the library of each Renderer you use:
npm install @tiptap-pro/extension-diagrams
npm install echartsThe examples on this page also use @tiptap/starter-kit and the optional @tiptap/extension-table.
Install them too if your editor does not have them yet.
A first chart
This editor uses the ECharts Renderer and inserts a bar chart from three rows of text. Your page
needs an element with the id editor:
import { Editor } from '@tiptap/core'
import StarterKit from '@tiptap/starter-kit'
import { TableKit } from '@tiptap/extension-table'
import { Diagrams, chartStyleRules } from '@tiptap-pro/extension-diagrams'
import { echartsRenderer } from '@tiptap-pro/extension-diagrams/echarts'
const style = document.createElement('style')
style.textContent = chartStyleRules()
document.head.append(style)
const editor = new Editor({
element: document.querySelector('#editor'),
extensions: [
StarterKit,
TableKit,
Diagrams.configure({
renderers: [echartsRenderer()],
chart: { defaultType: 'bar' },
}),
],
})
editor.commands.insertChartFrom({
format: 'chart-syntax',
content: 'Month | Revenue\nJan | 120\nFeb | 150\nMar | 110',
})The editor shows a bar chart with three bars, and the chart is selected.
chartStyleRules() returns the charts' stylesheet as a string. defaultType
gives a new chart the type bar instead of line. chart-syntax is the
Chart syntax: one row per line, cells separated by |, the first row naming
the columns. TableKit is optional. With it, a chart can be turned into a table and back.
In this demo, edit the rows, press Insert chart, then apply another type:
Change it
updateChartSpec and updateChartAxis change the selected chart, such as the one
A first chart inserts:
editor.commands.updateChartSpec({ spec: { type: 'line', title: 'Revenue' } })
editor.commands.updateChartAxis({ axis: 'y', changes: { title: 'EUR', min: 0 } })The Chart Spec holds how a chart shows its data: type, title, colors and axes. Without a selected
chart, both commands return false. Every change is a command, so the user can undo
it and collaborators receive it. An AI model calls them through tools.
A second chart from the Quick Input
The Quick Input is a text field in the document that turns typed rows into a chart. It needs no option:
- Type
:::in an empty paragraph to open the Quick Input. - Enter rows such as
Apr | 130. - Press Enter on an empty last line.
A first diagram
A flow diagram needs a Diagram Renderer. The one for Mermaid, a library that draws diagrams from
text, needs mermaid:
npm install mermaidThis is the editor from A first chart with the Mermaid Diagram Renderer and the diagram styles, inserting a flowchart:
import { Editor } from '@tiptap/core'
import StarterKit from '@tiptap/starter-kit'
import { TableKit } from '@tiptap/extension-table'
import { Diagrams, chartStyleRules, flowDiagramStyleRules } from '@tiptap-pro/extension-diagrams'
import { echartsRenderer } from '@tiptap-pro/extension-diagrams/echarts'
import { mermaidDiagramRenderer } from '@tiptap-pro/extension-diagrams/mermaid'
import rendererUrl from '@tiptap-pro/extension-diagrams/mermaid-renderer?url&no-inline'
import mermaidUrl from 'mermaid/dist/mermaid.min.js?url'
const style = document.createElement('style')
style.textContent = chartStyleRules() + flowDiagramStyleRules()
document.head.append(style)
const editor = new Editor({
element: document.querySelector('#editor'),
extensions: [
StarterKit,
TableKit,
Diagrams.configure({
renderers: [echartsRenderer()],
diagramRenderers: [mermaidDiagramRenderer({ mermaidUrl, rendererUrl })],
chart: { defaultType: 'bar' },
}),
],
})
editor.commands.insertFlowDiagram({
source: 'flowchart LR\n order[Order placed] --> ship[Shipped]',
title: 'Order flow',
})The editor shows a flowchart with two boxes, and the diagram is selected.
Mermaid draws in a sandboxed iframe from two files your bundler serves: mermaidUrl is Mermaid,
rendererUrl the script that draws with it. In Vite, ?url gives a file's URL, and no-inline
keeps a small file from becoming a data URL, which the iframe cannot load. The
Mermaid Renderer covers other bundlers.
Packages
Diagrams needs Tiptap 3.31 or a later 3.x release. You install a library only for its Renderer:
| Package | Kind | Version |
|---|---|---|
@tiptap/core, @tiptap/pm | Peer dependency | ^3.31.0 |
fflate | Dependency | ^0.8.3, installed with the package |
echarts | Optional peer dependency | ^6.0.0 |
d3 | Optional peer dependency | ^7.9.0 |
d3-sankey | Optional peer dependency | ^0.12.3, for sankey charts with D3 |
mermaid | Optional peer dependency | >=11.16.1 <13 |
pele | Optional peer dependency | 1.6.0, for Pele, a smaller Mermaid |
bpmn-js | A file you serve | Tested with 18.31 |
| draw.io viewer | A file you serve | Tested with 32.4.1 |
Without d3-sankey, the D3 Renderer leaves sankey charts to another Renderer, or
they show the unavailable text. The
draw.io and BPMN Renderers load their
library from a file you serve, so your package manager does not check its version.
Renderers lists every Renderer.
Entry points
Each Renderer is its own entry point, so your bundle holds only the libraries you use. Entries ship ES modules and CommonJS with types, except the sandbox scripts in the last row:
| Import from | What it holds |
|---|---|
@tiptap-pro/extension-diagrams | Diagrams (also the default export), nodes, commands, Data Sources, export, styling, AI tools. No chart library |
@tiptap-pro/extension-diagrams/core | Data types, parsers, formats and the Word writer, without Tiptap or DOM, for a server or worker |
@tiptap-pro/extension-diagrams/export | SVG to PNG, WebP, JPEG or a download in the browser, such as svgToImage, downloadBlob |
@tiptap-pro/extension-diagrams/theme | Colors from CSS custom properties in the browser, such as readChartTheme |
@tiptap-pro/extension-diagrams/echarts | Charts drawn with ECharts: echartsRenderer |
@tiptap-pro/extension-diagrams/d3 | Charts drawn with D3: d3Renderer |
@tiptap-pro/extension-diagrams/mermaid | Charts and diagrams drawn with Mermaid: mermaidRenderer and mermaidDiagramRenderer |
@tiptap-pro/extension-diagrams/drawio | draw.io diagrams: drawioDiagramRenderer |
@tiptap-pro/extension-diagrams/bpmn | BPMN process models: bpmnDiagramRenderer |
@tiptap-pro/extension-diagrams/pele | Mermaid diagrams drawn by Pele, smaller than Mermaid, in a Web Worker: peleDiagramRenderer |
@tiptap-pro/extension-diagrams/pele-worker | The Pele Web Worker, loaded with your bundler's Worker import |
@tiptap-pro/extension-diagrams/pele-render | Drawing with Pele without a web page, such as on a server. It imports pele directly |
@tiptap-pro/extension-diagrams/mermaid-renderer, /drawio-renderer, /bpmn-renderer | The sandboxed iframe's scripts, served as files, with their URL passed as rendererUrl |
Next
By topic: