---
title: "Options"
description: "Every option of the Diagrams extension and of its chart Node, by topic."
canonical_url: "https://tiptap-docs.lin52025i.qzz.io/diagrams/api-reference/options"
---

# Options

Every option of the Diagrams extension and of its chart Node, by topic.

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

| Topic                                                                                                   | Options                                                                                                          |
| ------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
| [Renderers](https://tiptap-docs.lin52025i.qzz.io/diagrams/api-reference/options.md#renderers)           | `renderers`, `diagramRenderers`, `defaultRenderer`, `chartTypes`, `rendererRules`                                |
| [Data](https://tiptap-docs.lin52025i.qzz.io/diagrams/api-reference/options.md#data)                     | `sources`, `formats`, `fetch`, `allowSourceUrl`, `onSourceError`                                                 |
| [Input](https://tiptap-docs.lin52025i.qzz.io/diagrams/api-reference/options.md#input)                   | `trigger`, `codeBlockShortcut`                                                                                   |
| [Display](https://tiptap-docs.lin52025i.qzz.io/diagrams/api-reference/options.md#display)               | `resizable`, `lazyRendering`, `animation`, `sourceHighlighting`, `styles`, `colorScheme`, `unavailable`          |
| [Export](https://tiptap-docs.lin52025i.qzz.io/diagrams/api-reference/options.md#export)                 | `docxImages`, `uploadImage`, `imageNodeName`                                                                     |
| [Nodes](https://tiptap-docs.lin52025i.qzz.io/diagrams/api-reference/options.md#nodes)                   | `chart`, `flowDiagram`                                                                                           |
| [The chart node](https://tiptap-docs.lin52025i.qzz.io/diagrams/api-reference/options.md#the-chart-node) | `defaultType`, `placeholder`, `delimiters`, `decimalSeparator`, `linkTables`, `minRenderWidth`, `HTMLAttributes` |

## Renderers

### renderers

`ChartRenderer[]` · Default `[]`

The Renderers that can draw a chart. See [Renderers](https://tiptap-docs.lin52025i.qzz.io/diagrams/renderers/overview.md). Without a Renderer,
a chart shows what [`unavailable`](https://tiptap-docs.lin52025i.qzz.io/diagrams/api-reference/options.md#unavailable) returns.

### diagramRenderers

`DiagramRenderer[]` · Default `[]`

The Diagram Renderers that can draw a diagram. See [Diagrams](https://tiptap-docs.lin52025i.qzz.io/diagrams/flow-diagrams/overview.md). Without a
Diagram Renderer, a diagram shows what [`unavailable`](https://tiptap-docs.lin52025i.qzz.io/diagrams/api-reference/options.md#unavailable) returns.

| Diagram Renderer         | Imported from                            |
| ------------------------ | ---------------------------------------- |
| `mermaidDiagramRenderer` | `@tiptap-pro/extension-diagrams/mermaid` |
| `drawioDiagramRenderer`  | `@tiptap-pro/extension-diagrams/drawio`  |
| `bpmnDiagramRenderer`    | `@tiptap-pro/extension-diagrams/bpmn`    |

### 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](https://tiptap-docs.lin52025i.qzz.io/diagrams/renderers/custom-chart-types.md).

### 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](https://tiptap-docs.lin52025i.qzz.io/diagrams/renderers/custom.md#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](https://tiptap-docs.lin52025i.qzz.io/diagrams/data/sources.md).

### 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](https://tiptap-docs.lin52025i.qzz.io/diagrams/data/sources.md#reading-a-url).

```ts
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](https://tiptap-docs.lin52025i.qzz.io/diagrams/data/sources.md).

## 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](https://tiptap-docs.lin52025i.qzz.io/diagrams/data/quick-input.md#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](https://tiptap-docs.lin52025i.qzz.io/diagrams/guides/size-and-view.md#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](https://tiptap-docs.lin52025i.qzz.io/diagrams/api-reference/selectors.md#highlighted-source).
A text field of your own can show them with [`highlightSource`](https://tiptap-docs.lin52025i.qzz.io/diagrams/guides/split-view.md).

### 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](https://tiptap-docs.lin52025i.qzz.io/diagrams/guides/styling.md#styles).

```ts
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](https://tiptap-docs.lin52025i.qzz.io/diagrams/guides/styling.md#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? }`:

| Field    | Value                                                                                                                                                               |
| -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `kind`   | `'chart'` or `'flowDiagram'`                                                                                                                                        |
| `reason` | `'no-renderer'`, or `'unsupported-kind'` for a kind no registered Renderer draws                                                                                    |
| `pos`    | Its position, for a command or a [storage function](https://tiptap-docs.lin52025i.qzz.io/diagrams/api-reference/storage.md). `null` while it is not in the document |
| `title`  | Its title, or `null`                                                                                                                                                |
| `type`   | A chart's type                                                                                                                                                      |
| `format` | A diagram's format                                                                                                                                                  |

To let a user open the data, return a button that reads it when pressed: a chart's data with
[`read`](https://tiptap-docs.lin52025i.qzz.io/diagrams/api-reference/storage.md) or `readTable`, a diagram's source with `listDiagrams`. Here, `openDialog`
is a dialog of your own. You can also show the data in place.

```ts
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](https://tiptap-docs.lin52025i.qzz.io/diagrams/export.md#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](https://tiptap-docs.lin52025i.qzz.io/diagrams/api-reference/options.md#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`](https://tiptap-docs.lin52025i.qzz.io/diagrams/guides/collaboration.md#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.

```ts
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](https://tiptap-docs.lin52025i.qzz.io/diagrams/renderers/custom-chart-types.md).
- 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](https://tiptap-docs.lin52025i.qzz.io/diagrams/data/chart-syntax.md#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](https://tiptap-docs.lin52025i.qzz.io/diagrams/data/tables.md).

### 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.

```ts
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.