Options
Diagrams.configure(), with the options of the chart node under chart.Most editors set the Renderers, the type of a new chart and the resize handles. Each Renderer
needs its library installed, here echarts and d3:
import { Diagrams } from '@tiptap-pro/extension-diagrams'
import { d3Renderer } from '@tiptap-pro/extension-diagrams/d3'
import { echartsRenderer } from '@tiptap-pro/extension-diagrams/echarts'
const diagrams = Diagrams.configure({
renderers: [echartsRenderer(), d3Renderer()],
defaultRenderer: 'echarts',
resizable: true,
chart: { defaultType: 'bar', linkTables: true },
})Add diagrams to your editor's extensions, as in A first chart.
A row named chart.… goes inside chart: {}. The Quick Input is the text field that typing :::
opens in an empty paragraph, where the user types rows that become a chart.
| Option | Type | Default | Description |
|---|---|---|---|
renderers | ChartRenderer[] | [] | Chart Renderers |
diagramRenderers | DiagramRenderer[] | [] | Diagram Renderers |
defaultRenderer | string | null | null | Renderer of a chart that names none |
chartTypes | ChartTypeDefinition[] | [] | Your chart types |
rendererRules | Record<string, RendererRules> | {} | Credit and export formats, by Renderer id |
sources | ChartSourceProvider[] | [] | Your Data Source providers |
formats | ChartFormat[] | [] | Languages charts are written in as text |
fetch | typeof globalThis.fetch | null | null | How URL providers fetch |
allowSourceUrl | ((url: URL) => boolean) | null | null | Which URLs a chart may read |
onSourceError | function or null | null | Called when a source fails |
trigger | string | ':::' | Opens the Quick Input |
codeBlockShortcut | string | false | 'Mod-Enter' | Turns Mermaid code into a chart or diagram |
resizable | boolean | false | Resize handles |
lazyRendering | boolean | true | Draw near the viewport only |
animation | boolean | true | Animated charts |
sourceHighlighting | boolean | true | Colored source text |
styles | ChartStyle[] | [] | Your chart styles |
colorScheme | 'auto' | 'light' | 'auto' | Follow dark mode, or stay light |
unavailable | (figure) => string | HTMLElement | null | A sentence | What shows without a Renderer |
docxImages | 'auto' | 'always' | 'auto' | Word charts or images |
uploadImage | function or null | null | Uploads a chart image |
imageNodeName | string | 'image' | The image node to create |
chart | Partial<ChartOptions> | false | {} | chart node options |
flowDiagram | Partial<FlowDiagramOptions> | false | {} | flowDiagram node options |
chart.defaultType | ChartType | 'line' | Type of a new chart |
chart.placeholder | string | function | false | Example rows | Hint of an empty Quick Input |
chart.delimiters | string[] | [',', ';', '|', '\t'] | Cell delimiters |
chart.decimalSeparator | 'auto' | '.' | ',' | 'auto' | How numbers are read |
chart.linkTables | boolean | false | Charts that follow a table |
chart.minRenderWidth | number | null | null | Narrowest layout width |
chart.HTMLAttributes | Record<string, unknown> | {} | Root element attributes |
Renderers
A Renderer connects the extension to one drawing library.
renderers
The Renderers that draw charts, listed on Renderers. Without one, a chart
shows what unavailable returns.
diagramRenderers
The Renderers that draw flow diagrams: mermaidDiagramRenderer, drawioDiagramRenderer,
bpmnDiagramRenderer and peleDiagramRenderer (Pele, a smaller Mermaid renderer), from
@tiptap-pro/extension-diagrams/mermaid, /drawio, /bpmn and /pele. Without one, a diagram
shows what unavailable returns.
defaultRenderer
The id of the Renderer for a chart that names none. A chart is drawn by the Renderer it names, then
by defaultRenderer, then by the first registered Renderer that draws its type.
chartTypes
Chart types added to the built-in ones, each { id, label, shape, word, description? }, with
shape how it reads rows and word its Word form. One with a built-in id replaces that type. An id
is 1 to 64 letters, digits, _ or -, and others are dropped silently. See
Register your own chart type.
rendererRules
A credit link a library's license asks for, and the formats files may be exported in, keyed by
Renderer id. A key matches every Renderer with that id: echarts, d3, mermaid (charts and
diagrams), drawio, bpmn, pele, or your own.
Diagrams.configure({
rendererRules: {
drawio: { attribution: { label: 'draw.io', href: 'https://www.drawio.com' } },
echarts: { exports: ['svg', 'png'] },
},
})| Rule | Type | What it does |
|---|---|---|
attribution | { label: string, href: string, logo?: string } | A credit below each chart or diagram and in its files. Used only if the Renderer declares none |
exports | ('svg' | 'png' | 'webp' | 'jpeg' | 'docx')[] | The allowed formats. With a list from the Renderer too, only formats in both |
Of the built-in Renderers, only BPMN declares rules, a bpmn.io credit, so your rules cannot remove
it. Without any exports list, every format is allowed.
export throws The Renderer <id> does not allow exporting <format>. for a format not
allowed. Without docx, exportDocx still writes native Word charts, which need
no picture. It leaves out diagrams and charts Word shows only as pictures, and lists them in
notes.
editor.storage.diagrams.rulesFor(renderer) returns a Renderer's rules in effect. See
Adding rules.
Data
A Data Source is a place outside the document a chart reads data from, and a provider reads one kind of Data Source.
sources
Providers added to the built-in url-csv, url-json and document-table. One with a built-in id
replaces that provider. See Data Sources.
formats
Languages a chart is written in as text, added to chart-json, chart-syntax and mermaid. The
id is what insertChartFrom, updateChartFrom, read and the AI tools take as format. One with
a built-in id replaces that format.
| Field | Type | Description |
|---|---|---|
id | string | The name passed as format |
description | string | When to use it, for an AI model |
mediaType | 'json' | 'text' | The kind of content |
schema | object | Optional JSON Schema of the content |
example | string | A complete, valid example |
parse | (content, options?) => { data, spec, delimiter? } | Reads content, throwing a message on an error |
serialize | (data, spec, options?) => string | Writes the Chart Data and Chart Spec |
parse options are type, delimiters and decimalSeparator, and serialize options are
delimiter and decimalSeparator.
fetch
The fetch the URL providers read with. The default null uses globalThis.fetch. Pass your own
for credentials or a proxy.
allowSourceUrl
Decides which http: and https: URLs url-csv and url-json may read, and refuses others with
a ChartSourceError. Without it, any such URL is read, but the insertLinkedChart tool for an
AI model refuses URL sources. See
Reading a URL.
Diagrams.configure({
allowSourceUrl: url => url.hostname === 'data.example.com',
})onSourceError
(error: unknown, source: { provider, address }) => void, called when a Data Source cannot be
read. The chart keeps its last snapshot. See Data Sources.
Input
These options turn typed text into a chart or a diagram.
trigger
The text that opens the Quick Input when typed into an empty paragraph. In a code block, or beside other text, it stays text.
codeBlockShortcut
The key that turns Mermaid source in a code block into a chart, for a Mermaid chart such as pie,
or else into a diagram, as Mod-Enter in a code block
describes. Mod is Cmd on macOS and Ctrl elsewhere. false adds no key. This option does not
change the Quick Input, which always confirms with Mod-Enter.
Display
How charts and diagrams behave in the editor.
resizable
true puts resize handles on a selected chart or diagram while
the editor is editable.
lazyRendering
true draws a chart or a diagram once it comes within half a screen of the viewport, and draws a
change far away when it comes near. Until then, a chart keeps its height and a diagram is a few
lines tall. Exports are not affected.
false draws all of them as the document opens, and so does a browser without
IntersectionObserver. Use it for printed or captured pages, and in tests whose
IntersectionObserver does not report.
animation
true lets a Renderer animate a chart when it is first drawn and after its data or spec changes.
false draws the final state at once. Of the built-in Renderers, only ECharts animates. Diagrams
and exports are not animated, and nothing animates with prefers-reduced-motion: reduce.
sourceHighlighting
Colors keywords, labels, numbers, arrows, delimiters and comments in the Quick Input, and in a
Mermaid diagram that shows its source text instead of the picture. false leaves one color. See
Highlighted source.
styles
Styles a chart may name in spec.style, its Chart Spec's style field, added to the built-in ones, each
{ id, label, palette, appearance? }. One with a built-in id replaces that style. See
Styles.
Diagrams.configure({
styles: [
{
id: 'brand',
label: 'Brand',
palette: ['#0b5fff', '#ff7a00'],
appearance: { fontFamily: 'Inter, sans-serif' },
},
],
})colorScheme
'auto' follows the web page's color scheme and redraws when the system scheme changes, as
Dark color scheme describes. 'light' keeps charts and
diagrams light.
unavailable
What a chart or a diagram shows when no registered Renderer draws its chart type, diagram format or
Mermaid kind: a string, an element, or null for nothing. The default is "This chart can't be
drawn here." or "This diagram can't be drawn here." The data stays unchanged. The function receives
figure:
| Field | Value |
|---|---|
kind | 'chart' or 'flowDiagram' |
reason | 'no-renderer' for a chart type or diagram format, 'unsupported-kind' for a Mermaid kind |
pos | Its position, or null outside the document |
title | Its title, or null |
type | A chart's type, absent for a diagram |
format | A diagram's format, absent for a chart |
The example returns a button that opens a chart's data, read with
read, or a diagram's source. editor is your editor and
openDialog a dialog of your own:
Diagrams.configure({
unavailable: figure => {
const button = document.createElement('button')
button.textContent = `Show the ${figure.kind === 'chart' ? 'data' : 'source'}`
button.addEventListener('click', () => {
const text =
figure.kind === 'chart'
? editor.storage.diagrams.read({ pos: figure.pos ?? -1, format: 'chart-syntax' })
: editor.storage.diagrams.listDiagrams().find(diagram => diagram.pos === figure.pos)
?.source
openDialog(text ?? '')
})
return button
},
})Export
How charts become images and Word content.
docxImages
How exportDocx, which writes the document as a Word file, writes charts when
its call passes no images. 'auto' writes a native Word chart or table for the types Word draws
correctly, else an image. 'always' writes images. See Charts as images.
uploadImage
(blob: Blob, meta) => Promise<string>, which uploads the image the command
convertChartToImage replaces a chart with, and returns its URL.
Without it, the image is a data URL. meta holds alt (from the title and description), width
and height in CSS pixels, and format: 'svg', 'png', 'webp' or 'jpeg'.
imageNodeName
The name of the image node convertChartToImage creates.
Nodes
Diagrams registers the chart, diagramInput (the Quick Input) and flowDiagram nodes.
chart
The options under The chart node. Set only those you change. false leaves out
charts and the Quick Input.
flowDiagram
{ HTMLAttributes }, the HTML attributes on the diagram's root element, default {}. false
leaves diagrams out. In a shared document, a client with false deletes the diagrams of every
client, unless it sets enableContentCheck: true with @tiptap/extension-collaboration 3.33.0 and
@tiptap/y-tiptap 3.2.0 or later. See
A client without Diagrams.
The chart node
These options go under chart.
defaultType
The type of a new chart when nothing names another: in the Quick Input, in insertChart, when a
table becomes a chart, and in the storage function parseFormat.
Chart types lists the ids.
placeholder
The hint an empty Quick Input shows. The default is example rows for its chart type and delimiter,
and the line Enter twice to finish.
Diagrams.configure({
chart: {
placeholder: ({ type }) => (type === 'pie' ? 'Label, share' : 'Label, value, value …'),
},
})A function receives { type, shape, delimiter } and runs again when the type changes. shape is
how the type reads its rows, also for a registered type, and delimiter is the one
the Quick Input suggests. Line breaks are kept, and false shows no hint.
delimiters
The delimiters that may separate cells in typed rows, the Chart syntax. The
first line that contains one decides for all rows. On a line with several, tab wins over |, ;
and ,.
decimalSeparator
How numbers in typed rows and tables are read. See Numbers.
linkTables
Lets a chart or a diagram follow a table in the document, and adds chartTableId to the table
node. Without it, insertLinkedChart, linkChartToTable, setChartLayout with a table,
insertDiagramFromTable and linkDiagramToTable return false, and listTables() is empty. See
Tables.
minRenderWidth
In a column narrower than this many pixels, a chart is drawn this wide and scaled down, text
included, as Narrow screens describes. null draws at the shown
width. An export uses its own size.
Diagrams.configure({ chart: { minRenderWidth: 560 } })HTMLAttributes
HTML attributes on the chart's root element.
Requirements on the schema
The extension does not register table or image nodes, so you register them yourself. It adds its attributes to the ones you register.
The commands that turn a chart into a table and back, the linked tables, and the Quick Input's
table view need the nodes table, tableRow, tableHeader, tableCell and paragraph, such as
those of @tiptap/extension-table and StarterKit. Without them, those commands return false.
convertChartToImage returns false without the image node named by imageNodeName.