Options

Diagrams.configure({
  renderers: [echartsRenderer(), d3Renderer()],
  defaultRenderer: 'echarts',
  chart: { defaultType: 'bar', linkTables: true },
})

Renderers

renderers

ChartRenderer[] · Default []

The Renderers that can draw a chart. See Renderers. Without a Renderer, a chart shows what unavailable returns.

diagramRenderers

DiagramRenderer[] · Default []

The Diagram Renderers that can draw a diagram. See Diagrams. Without a Diagram Renderer, a diagram shows what unavailable returns.

defaultRenderer

string | null · Default null

The id of the Renderer that draws a chart that names no Renderer. Without it, the chart gets the first registered Renderer that draws its type.

chartTypes

{ id, label, shape, word, description? }[] · Default []

Chart types you add to the built-in ones. A type with the id of a built-in type replaces it. See Register your own chart type.

rendererRules

Record<string, { attribution?, exports? }> · Default {}

Rules you add to the rules a Renderer declares, keyed by Renderer id. They can only make a Renderer stricter. See Adding rules.

Data

sources

ChartSourceProvider[] · Default []

Data Source providers you add to the built-in url-csv, url-json and document-table. See Data Sources.

formats

ChartFormat[] · Default []

Text formats you add to chart-json, chart-syntax and mermaid. A format is { id, description, mediaType, schema?, example, parse, serialize }. A format with the id of a built-in format replaces it.

fetch

typeof globalThis.fetch | null · Default globalThis.fetch

The fetch function the URL providers read with. Pass your own to add credentials or to go through a proxy.

allowSourceUrl

((url: URL) => boolean) | null · Default null

Decides which URLs url-csv and url-json may read. Without it, they read any absolute http: or https: URL, and the AI tool insertLinkedChart refuses URL sources. See Reading a URL.

Diagrams.configure({
  allowSourceUrl: (url) => url.hostname === 'data.example.com',
})

onSourceError

((error, { provider, address }) => void) | null · Default null

Called when a Data Source cannot be read. The chart keeps its last snapshot. See Data Sources.

Input

trigger

string · Default ':::'

The text that opens the Quick Input when you type it at the start of an empty paragraph.

codeBlockShortcut

string | false · Default 'Mod-Enter'

The key that turns Mermaid source in the code block at the selection into a chart or a diagram, and confirms the Quick Input. false adds no key. See Mod-Enter in a code block.

Display

resizable

boolean · Default false

true puts resize handles on a selected chart or diagram while the editor is editable. What each handle does is under Resize handles.

lazyRendering

boolean · Default true

true draws a chart or a diagram only once it comes within half a screen of the viewport. It starts drawing at most one chart or diagram per animation frame.

• A change to a chart or diagram far from the viewport, such as an edit, a synchronized Data Source or a new theme, is drawn when it comes near again.
• Until it is drawn, a chart keeps its height and a diagram is a few lines tall.
• Exports draw on their own and are not affected.
• Without IntersectionObserver, every chart and diagram is drawn as with false.

false draws every chart and diagram as the document opens, still one per frame. Use it for a page that is printed or captured as a whole, and in tests whose DOM implementation has an IntersectionObserver that never reports.

animation

boolean · Default true

true lets a Renderer animate a chart when it is first drawn and when its data or spec changes. false draws every chart in its final state at once.

• The ECharts Renderer animates.
• The D3 and Mermaid Renderers never animate. Diagrams never animate either.
• When the viewer's system asks for reduced motion (prefers-reduced-motion: reduce), nothing animates, whatever this option says.
• Exports are never animated.

sourceHighlighting

boolean · Default true

Colors the parts of the text in the Quick Input and in a Mermaid diagram's code view: keywords, labels, numbers, arrows and delimiters, and comments. false leaves the text in one color. The colors and their classes are under Highlighted source. A text field of your own can show them with highlightSource.

styles

ChartStyle[] · Default []

Styles a chart may name in spec.style, in addition to the built-in ones. A style with the id of a built-in one replaces it. See Styles.

Diagrams.configure({
  styles: [
    {
      id: 'brand',
      label: 'Brand',
      palette: ['#0b5fff', '#ff7a00'],
      appearance: { fontFamily: 'Inter, sans-serif' },
    },
  ],
})

colorScheme

'auto' | 'light' · Default 'auto'

The color scheme charts and diagrams are drawn in. 'auto' uses the color scheme of the web page, as described under Dark color scheme. 'light' draws them light on any page.

unavailable

(figure) => string | HTMLElement | null · Default: a sentence saying the chart or the diagram can't be drawn here

What a chart or a diagram shows in its place when no registered Renderer draws its chart type, its diagram format or the kind of its Mermaid source. Return a string, an element, or null to show nothing. The data stays in the document unchanged, and none of it is shown unless you show it.

The function receives figure, { kind, reason, pos, title, type?, format? }:

To let a user open the data, return a button that reads it when pressed: a chart's data with read or readTable, a diagram's source with listDiagrams. Here, openDialog is a dialog of your own. You can also show the data in place.

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

docxImages

'auto' | 'always' · Default 'auto'

How exportDocx writes charts when the call does not pass images. 'auto' writes a Word chart or a Word table where Word shows the chart correctly, and an image otherwise. 'always' writes every chart as an image. See Charts as images.

uploadImage

((blob, { alt, width, height, format }) => Promise<string>) | null · Default null

Uploads an image made by convertChartToImage and returns its URL. Without it, the image is stored as a data URL.

imageNodeName

string · Default 'image'

The name of the image node that convertChartToImage creates.

Nodes

chart

Partial<ChartOptions> | false · Default {}

The options of the chart node, listed under The chart node. false leaves charts out.

flowDiagram

Partial<FlowDiagramOptions> | false · Default {}

The options of the flowDiagram node. FlowDiagramOptions is { HTMLAttributes }, the HTML attributes on the diagram's root element, with the 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

ChartType · Default 'line'

The type a new chart gets when nothing names another type, for example in the Quick Input or in a converted table.

placeholder

string | (({ type, shape, delimiter }) => string) | false · Default: example rows for the Quick Input's chart type, and the line Enter twice to finish

The hint an empty Quick Input shows.

Diagrams.configure({
  chart: {
    placeholder: ({ type }) => (type === 'pie' ? 'Label, share' : 'Label, value, value …'),
  },
})

• A function is called again when the chart type of the Quick Input changes.
• shape is the layout of rows the chart type reads, also for a type registered with chartTypes. See Register your own chart type.
• Line breaks in the hint are kept.
• false shows no hint.

delimiters

string[] · Default [',', ';', '|', '\t']

The delimiters the Chart syntax may use to separate cells.

decimalSeparator

'auto' | '.' | ',' · Default 'auto'

How numbers in the rows of a chart are read. See Numbers.

linkTables

boolean · Default false

Allows a chart to follow a table in the same document, with insertLinkedChart, linkChartToTable and setChartLayout. It adds the attribute chartTableId to the table node. See Tables.

minRenderWidth

number | null · Default null

When the editor's text is narrower than this many pixels, a chart is drawn this wide and scaled down to fit, text included.

Diagrams.configure({ chart: { minRenderWidth: 560 } })

On a phone, the chart keeps its wide-screen layout instead of crowding into the narrow width.

• The scale goes no lower than 60 %. Below that, the chart is laid out more densely and leaves out category labels that would overlap, unless axes.x.labels chooses them.
• null always draws at the width shown.
• A maximized chart and an export are drawn at their own size.

HTMLAttributes

Record<string, unknown> · Default {}

HTML attributes on the chart's root element.

Requirements on the schema

The table commands and the table view of the Quick Input use the nodes registered as table, tableRow, tableHeader and tableCell, such as those of @tiptap/extension-table. Without those nodes, those commands return false.

convertChartToImage needs the image node named by imageNodeName.

The extension adds attributes to these nodes. It never registers nodes of its own under their names.