Install Diagrams

Install

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 below also use @tiptap/starter-kit and @tiptap/extension-table. Install them too if your editor does not have them yet.

The draw.io and BPMN Renderers load their library from a file you serve. See draw.io and BPMN. Renderers lists every Renderer.

A first chart

In the demo, write rows as text, insert them as a chart, then change its type:

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 now holds a bar chart with three bars, and the chart is selected.

• chartStyleRules() returns the stylesheet the charts need.
• TableKit is optional. With it, you can turn a chart into a table and back.
• chart: { defaultType: 'bar' } gives a new chart the type bar. See defaultType.
• chart-syntax is the Chart syntax: one row per line, with the cells separated by |.

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

1. Type ::: in an empty paragraph to open the Quick Input, a text field inside the document.
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@11

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.

Entry points

Each Renderer is its own entry point of the package. Your bundle then holds only the libraries you use.

Next

• 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