Charts and diagrams, right where you write

The Diagrams extension lets the users of your Tiptap editor insert charts and flow diagrams and change them like the text around them. Each one is stored in the document as data, not as a picture, so it stays editable, users can undo their changes, and collaborators see them. Install Diagrams sets it up.

Try Diagrams with charts, flow diagrams, the Quick Input and Word export.

New tab

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 echarts

With 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

ToUse
Insert a chart from rows of textinsertChartFrom({ format: 'chart-syntax', content })
Insert a chart from data in codeinsertChart({ data, spec })
Let users type a chartTyping ::: in an empty paragraph, see Quick Input
Turn the table at the cursor into a chartconvertTableToChart({ type: 'bar' })
Read a chart's data from a CSV URLlinkChartSource({ provider: 'url-csv', address })
Change the type or the titleupdateChartSpec({ spec: { type: 'line' } })
Change an axisupdateChartAxis({ axis: 'y', changes: { min: 0 } })
Insert a Mermaid diagraminsertFlowDiagram({ source })
Set the size of a chart or a diagramsetDiagramSize({ size })
Save a chart as a PNG fileeditor.storage.diagrams.export({ pos }, { format: 'png' })
Put every chart into a Word documenteditor.storage.diagrams.exportDocx()
Give an AI model tools for chartsgetChartToolDefinitions(editor)

Words these pages use

WordMeaning
Chart DataThe values a chart stores, as columns and rows. Data
Chart SpecA chart's settings, such as its type, title, colors and axes. Appearance
Chart syntaxRows typed as text, one per line, with cells split by |, such as Jan | 2. Chart syntax
Quick InputThe text field that typing ::: opens in an empty paragraph. Quick Input
RendererThe adapter between the extension and one chart library, such as ECharts. Renderers
Diagram RendererA Renderer that draws diagrams, such as the one for Mermaid. Renderers
Data SourceA place outside the document that a chart reads its values from, such as a CSV file. Data Sources