Install Diagrams

The Diagrams extension adds charts and flow diagrams to a Tiptap editor. A library such as ECharts draws them, through a Renderer you register for each library.

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:

  1. Contact our team to join the Tiptap Diagrams pilot program.
  2. Configure your package manager by following the private registry guide.
  3. Install the package and the library of each Renderer you use:
npm install @tiptap-pro/extension-diagrams
npm install echarts

The 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:

New tab

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:

  1. Type ::: in an empty paragraph to open the Quick Input.
  2. Enter rows such as Apr | 130.
  3. 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 mermaid

This 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:

PackageKindVersion
@tiptap/core, @tiptap/pmPeer dependency^3.31.0
fflateDependency^0.8.3, installed with the package
echartsOptional peer dependency^6.0.0
d3Optional peer dependency^7.9.0
d3-sankeyOptional peer dependency^0.12.3, for sankey charts with D3
mermaidOptional peer dependency>=11.16.1 <13
peleOptional peer dependency1.6.0, for Pele, a smaller Mermaid
bpmn-jsA file you serveTested with 18.31
draw.io viewerA file you serveTested 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 fromWhat it holds
@tiptap-pro/extension-diagramsDiagrams (also the default export), nodes, commands, Data Sources, export, styling, AI tools. No chart library
@tiptap-pro/extension-diagrams/coreData types, parsers, formats and the Word writer, without Tiptap or DOM, for a server or worker
@tiptap-pro/extension-diagrams/exportSVG to PNG, WebP, JPEG or a download in the browser, such as svgToImage, downloadBlob
@tiptap-pro/extension-diagrams/themeColors from CSS custom properties in the browser, such as readChartTheme
@tiptap-pro/extension-diagrams/echartsCharts drawn with ECharts: echartsRenderer
@tiptap-pro/extension-diagrams/d3Charts drawn with D3: d3Renderer
@tiptap-pro/extension-diagrams/mermaidCharts and diagrams drawn with Mermaid: mermaidRenderer and mermaidDiagramRenderer
@tiptap-pro/extension-diagrams/drawiodraw.io diagrams: drawioDiagramRenderer
@tiptap-pro/extension-diagrams/bpmnBPMN process models: bpmnDiagramRenderer
@tiptap-pro/extension-diagrams/peleMermaid diagrams drawn by Pele, smaller than Mermaid, in a Web Worker: peleDiagramRenderer
@tiptap-pro/extension-diagrams/pele-workerThe Pele Web Worker, loaded with your bundler's Worker import
@tiptap-pro/extension-diagrams/pele-renderDrawing with Pele without a web page, such as on a server. It imports pele directly
@tiptap-pro/extension-diagrams/mermaid-renderer, /drawio-renderer, /bpmn-rendererThe sandboxed iframe's scripts, served as files, with their URL passed as rendererUrl

Next

By topic:

  • Data: typed rows, tables and Data Sources
  • Charts: types, appearance, axes, reference lines
  • Diagrams: Mermaid, draw.io and BPMN
  • Styling: colors, dark mode, your own classes