Install Diagrams

Install the package and a chart library, insert a first chart, then change it with a Command.

Alpha

Diagrams is a Pro extension in alpha. The API may change in future releases. Before installing, set up access to Tiptap's private npm registry.

Install

npm install @tiptap-pro/extension-diagrams
# and the library of each Renderer you use
npm install echarts

Package	Kind	Version
`@tiptap/core`, `@tiptap/pm`	Peer dependency	3.31 or later
`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 <12`

A Renderer draws charts with one library, such as ECharts. Register one for each library you install. Renderers
Install only the libraries of the Renderers you register.

Entry points

The Renderers are entry points of the package, so a bundle holds only the libraries you use.

Import from	What it holds
`@tiptap-pro/extension-diagrams`	`Diagrams`, its Nodes and Commands, Data Sources, export, styling and tools for a model
`@tiptap-pro/extension-diagrams/core`	The data model, parsers and formats, and the Word writer, without Tiptap and without a DOM, for a server or a worker
`@tiptap-pro/extension-diagrams/export`	Turning an SVG into a PNG, WebP or a download, in the browser
`@tiptap-pro/extension-diagrams/theme`	Reading chart and diagram colors from CSS custom properties, in the browser
`@tiptap-pro/extension-diagrams/echarts`	Charts drawn with ECharts
`@tiptap-pro/extension-diagrams/d3`	Charts drawn with d3
`@tiptap-pro/extension-diagrams/mermaid`	Charts and diagrams drawn with Mermaid
`@tiptap-pro/extension-diagrams/drawio`	draw.io diagrams
`@tiptap-pro/extension-diagrams/bpmn`	BPMN processes
`@tiptap-pro/extension-diagrams/pele`	Mermaid diagrams drawn by Pele in a Web Worker, smaller than mermaid.js

A first chart

Write rows as text, insert them as a chart, then change its type:

New tab

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',
})

chartStyleRules() returns the stylesheet the charts need.
TableKit is optional. It lets a chart turn into a table and back.
chart-syntax is the chart syntax: one row per line, cells split by |.
The editor now holds a bar chart with three bars.

A second chart from the Quick Input

Type ::: in an empty paragraph to open the Quick Input.
Enter rows such as Apr | 130.
Press Enter on an empty last line.

Change it

editor.commands.updateChartSpec({ spec: { type: 'line', title: 'Revenue' } })
editor.commands.updateChartAxis({ axis: 'y', changes: { title: 'EUR', min: 0 } })

The Chart Spec is how a chart shows its data: type, title, colors, axes.
Both act on the selected chart.
Every change is a Command, so it undoes, reaches collaborators and can be called by a model.

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

PreviouslyOverview

Next upLive demo