Options

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

Renderers

renderers

ChartRenderer[] · Default []

The Renderers a chart can be drawn with. See Renderers.

• Without one, charts show what unavailable returns.

diagramRenderers

DiagramRenderer[] · Default []

The Diagram Renderers a diagram can be drawn with. See Diagrams.

• Without one, diagrams show what unavailable returns.

defaultRenderer

string | null · Default null

The id of the Renderer for a chart that names none.

• Without it, a chart gets the first registered Renderer that draws its type.

chartTypes

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

Chart types added to the built-in ones. See Register your own chart type.

• The input, the Commands and the tools accept a registered type.
• Any Renderer that lists the type in types draws it.

rendererRules

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

Rules added to those a Renderer declares, by Renderer id. See Rules of your Renderer.

• They add a credit or narrow the allowed export formats.
• They never remove either.

Data

sources

ChartSourceProvider[] · Default []

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

formats

ChartFormat[] · Default []

Formats in addition 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 the URL providers read with, for credentials or a proxy.

onSourceError

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

Called when a Data Source cannot be read.

• The chart keeps its last snapshot.

Input

trigger

string · Default ':::'

The text that opens the Quick Input when typed at the start of an empty paragraph.

codeBlockShortcut

string | false · Default 'Mod-Enter'

The key that turns the code block at the selection into a chart or a diagram. It is the same key that confirms the input box.

• A Mermaid chart, such as pie or sankey-beta, becomes a chart.
• Other Mermaid source becomes a diagram.
• A code block of anything else keeps what the key did before. In Tiptap, that is leaving the code block.
• false adds no key.

Display

resizable

boolean · Default false

true puts handles on a selected chart or diagram while the editor is editable.

• Where the handles are: at the left and right side, at the bottom, and at the two lower corners.
• A side handle changes the width.
• The bottom handle changes the height.
• A corner handle changes both.
• A centered figure grows on both sides from a side handle.
• A figure aligned left or right (setDiagramAlign) grows only on the side of the handle.
• A corner keeps the shape while the size has locked: true. Shift swaps that.
• Near the full width, a drag snaps to the edge of the column.
• A double click on a handle fills the column.
• When the drag ends, the size is written with setDiagramSize, so it is one undo step.

lazyRendering

boolean · Default true

true draws a chart or a diagram only once it comes within half a screen of the viewport.

• true starts at most one drawing per frame.
• A change to a figure far from the viewport (an edit, a synchronized Data Source, 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.
• false draws every chart and diagram as the document opens, still one per frame.
• For a page that is printed or captured as a whole, use false.
• In tests whose DOM implementation has an IntersectionObserver that never reports, use false.
• Without IntersectionObserver, every figure is drawn as with false.

animation

boolean · Default true

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

Diagrams.configure({ renderers: [echartsRenderer()], animation: false })

• The ECharts Renderer animates.
• The d3 and Mermaid Renderers never move, nor do diagrams.
• Reduced motion (prefers-reduced-motion: reduce) on the reader's system animates nothing, 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 are custom properties with a light and a dark value, each at 4.5:1 contrast or more. See Selectors.
• Your own source editor can show the same with highlightSource. See Text beside the picture.

styles

ChartStyle[] · Default []

Styles a chart may name in spec.style, in addition to the built-in ones. See Styles.

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

• A style with the id of a built-in one replaces it.

colorScheme

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

The color scheme charts and diagrams are drawn in. See Dark color scheme.

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 place of its picture when no Renderer here can draw it.

• When it is shown: no Renderer draws the figure's type or format, or its Mermaid source is of a kind no Renderer knows.
• What it returns: a string, an element, or null for nothing.
• The data stays in the document as it is. Nothing of it is shown unless you show it.

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

To let a reader open the data, return a button that reads the data when it is pressed: a chart's with read or readTable, a diagram's source with listDiagrams. Here openDialog stands for your own dialog; you could as well 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 its call does not pass 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 a data URL.

imageNodeName

string · Default 'image'

The name of the image Node convertChartToImage creates.

Nodes

chart

Partial<ChartOptions> | false · Default {}

The options of the chart Node, listed under The chart Node, or false to leave charts out.

flowDiagram

{ HTMLAttributes } | false · Default {}

The options of the flowDiagram Node, or false to leave diagrams out.

• In a shared document, a client with false cannot show a document that holds a diagram.
• With @tiptap/y-tiptap before 3.0.10, such a client deletes the diagrams of every client. See Collaboration.

The chart Node

These options go under chart.

defaultType

ChartType · Default 'line'

The type a new chart gets when nothing says otherwise, as in the Quick Input or a converted table.

placeholder

string | (({ type, shape, delimiter }) => string) | false · Default: example rows for the box's type and how 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 box's type changes.
• shape is how the type reads its rows, also for a type registered with chartTypes.
• Line breaks in the hint are kept.
• false shows no hint.

delimiters

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

The delimiters the chart syntax may use.

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 (insertLinkedChart, linkChartToTable, setChartLayout).

• Adds the attribute chartTableId to the table Node.

minRenderWidth

number | null · Default null

A chart in a column narrower than this many pixels is drawn this wide and scaled down to fit, text included.

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

• On a phone a chart keeps the layout it has on a wide screen, with smaller text, instead of crowding ticks, labels and bars into the column.
• The scale goes no lower than 60 %.
• In a narrower column 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 input view 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 and never registers Nodes of its own under their names.