Options

The options of the Diagrams extension choose the libraries that draw, where chart data may come from, and how charts and diagrams behave. You pass them to 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.

OptionTypeDefaultDescription
renderersChartRenderer[][]Chart Renderers
diagramRenderersDiagramRenderer[][]Diagram Renderers
defaultRendererstring | nullnullRenderer of a chart that names none
chartTypesChartTypeDefinition[][]Your chart types
rendererRulesRecord<string, RendererRules>{}Credit and export formats, by Renderer id
sourcesChartSourceProvider[][]Your Data Source providers
formatsChartFormat[][]Languages charts are written in as text
fetchtypeof globalThis.fetch | nullnullHow URL providers fetch
allowSourceUrl((url: URL) => boolean) | nullnullWhich URLs a chart may read
onSourceErrorfunction or nullnullCalled when a source fails
triggerstring':::'Opens the Quick Input
codeBlockShortcutstring | false'Mod-Enter'Turns Mermaid code into a chart or diagram
resizablebooleanfalseResize handles
lazyRenderingbooleantrueDraw near the viewport only
animationbooleantrueAnimated charts
sourceHighlightingbooleantrueColored source text
stylesChartStyle[][]Your chart styles
colorScheme'auto' | 'light''auto'Follow dark mode, or stay light
unavailable(figure) => string | HTMLElement | nullA sentenceWhat shows without a Renderer
docxImages'auto' | 'always''auto'Word charts or images
uploadImagefunction or nullnullUploads a chart image
imageNodeNamestring'image'The image node to create
chartPartial<ChartOptions> | false{}chart node options
flowDiagramPartial<FlowDiagramOptions> | false{}flowDiagram node options
chart.defaultTypeChartType'line'Type of a new chart
chart.placeholderstring | function | falseExample rowsHint of an empty Quick Input
chart.delimitersstring[][',', ';', '|', '\t']Cell delimiters
chart.decimalSeparator'auto' | '.' | ',''auto'How numbers are read
chart.linkTablesbooleanfalseCharts that follow a table
chart.minRenderWidthnumber | nullnullNarrowest layout width
chart.HTMLAttributesRecord<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'] },
  },
})
RuleTypeWhat 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.

FieldTypeDescription
idstringThe name passed as format
descriptionstringWhen to use it, for an AI model
mediaType'json' | 'text'The kind of content
schemaobjectOptional JSON Schema of the content
examplestringA complete, valid example
parse(content, options?) => { data, spec, delimiter? }Reads content, throwing a message on an error
serialize(data, spec, options?) => stringWrites 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:

FieldValue
kind'chart' or 'flowDiagram'
reason'no-renderer' for a chart type or diagram format, 'unsupported-kind' for a Mermaid kind
posIts position, or null outside the document
titleIts title, or null
typeA chart's type, absent for a diagram
formatA 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.