Alpha
Diagrams is in alpha and available through a pilot program. The API may change in future releases.
The Diagrams demo is a whole editor with charts, flow
diagrams, the Quick Input and Word export. To try it, type ::: in an empty paragraph, then rows such as Jan | 2.
What you get
The extension adds a chart node for bar, line, pie and other charts, and a flowDiagram node for
flowcharts, sequence diagrams and process models. A node is one block of a Tiptap document, such as
a paragraph or an image.
- Data: users type rows after
:::, paste them or turn a table into a chart, and a chart can follow a CSV file at a URL. - Charts: the chart types, and the titles, colors, axes and reference lines users change at any time.
- Flow diagrams: Mermaid, draw.io and BPMN diagrams written as text. Users edit a Mermaid diagram's text right in the picture.
- Renderers: the library that draws, such as ECharts or D3 for charts and Mermaid or draw.io for diagrams.
- Export: a chart or a diagram as an SVG, PNG, WebP or JPEG file, and charts in a Word document.
- Tools for a model: tools that let an AI model insert, read and change charts and diagrams.
- Styling: colors, dark mode and chart styles of your own.
A first look
Diagrams is available through a pilot program. Contact our team to join it, and the package comes from Tiptap's private registry. Then install the package and ECharts, a chart library:
npm install @tiptap-pro/extension-diagrams echartsWith Diagrams registered in an editor, this command
inserts a bar chart from three typed rows. The first line, bar, names the type:
editor.commands.insertChartFrom({
format: 'chart-syntax',
content: 'bar\nMonth | Revenue\nJan | 120\nFeb | 150\nMar | 110',
})Install Diagrams has the registry access and the complete editor around this call.
What stays the same
You save, undo and share charts and diagrams like the rest of the document. getJSON() holds
each chart's values and settings and each diagram's text, but not the picture. So switching to
another library changes how a chart looks, and not the document.
The built-in Renderers draw text stored in a document, such as Mermaid source, in a sandboxed iframe or a Web Worker, so it never runs as code in your page. A Diagram Renderer of your own receives that text as well, so follow Keeping your web page safe. Collaboration says what every client of a shared document needs.
Common tasks
| To | Use |
|---|---|
| Insert a chart from rows of text | insertChartFrom({ format: 'chart-syntax', content }) |
| Insert a chart from data in code | insertChart({ data, spec }) |
| Let users type a chart | Typing ::: in an empty paragraph, see Quick Input |
| Turn the table at the cursor into a chart | convertTableToChart({ type: 'bar' }) |
| Read a chart's data from a CSV URL | linkChartSource({ provider: 'url-csv', address }) |
| Change the type or the title | updateChartSpec({ spec: { type: 'line' } }) |
| Change an axis | updateChartAxis({ axis: 'y', changes: { min: 0 } }) |
| Insert a Mermaid diagram | insertFlowDiagram({ source }) |
| Set the size of a chart or a diagram | setDiagramSize({ size }) |
| Save a chart as a PNG file | editor.storage.diagrams.export({ pos }, { format: 'png' }) |
| Put every chart into a Word document | editor.storage.diagrams.exportDocx() |
| Give an AI model tools for charts | getChartToolDefinitions(editor) |
Words these pages use
| Word | Meaning |
|---|---|
| Chart Data | The values a chart stores, as columns and rows. Data |
| Chart Spec | A chart's settings, such as its type, title, colors and axes. Appearance |
| Chart syntax | Rows typed as text, one per line, with cells split by |, such as Jan | 2. Chart syntax |
| Quick Input | The text field that typing ::: opens in an empty paragraph. Quick Input |
| Renderer | The adapter between the extension and one chart library, such as ECharts. Renderers |
| Diagram Renderer | A Renderer that draws diagrams, such as the one for Mermaid. Renderers |
| Data Source | A place outside the document that a chart reads its values from, such as a CSV file. Data Sources |