---
title: "Options"
description: "Every option of the Diagrams extension and of its chart Node, by topic."
canonical_url: "https://tiptap.dev/docs/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.dev/docs/diagrams/api-reference/options.md#renderers)           | `renderers`, `diagramRenderers`, `defaultRenderer`, `chartTypes`, `rendererRules`                                |
| [Data](https://tiptap.dev/docs/diagrams/api-reference/options.md#data)                     | `sources`, `formats`, `fetch`, `onSourceError`                                                                   |
| [Input](https://tiptap.dev/docs/diagrams/api-reference/options.md#input)                   | `trigger`, `codeBlockShortcut`                                                                                   |
| [Display](https://tiptap.dev/docs/diagrams/api-reference/options.md#display)               | `resizable`, `lazyRendering`, `animation`, `sourceHighlighting`, `styles`, `colorScheme`, `unavailable`          |
| [Export](https://tiptap.dev/docs/diagrams/api-reference/options.md#export)                 | `docxImages`, `uploadImage`, `imageNodeName`                                                                     |
| [Nodes](https://tiptap.dev/docs/diagrams/api-reference/options.md#nodes)                   | `chart`, `flowDiagram`                                                                                           |
| [The chart Node](https://tiptap.dev/docs/diagrams/api-reference/options.md#the-chart-node) | `defaultType`, `placeholder`, `delimiters`, `decimalSeparator`, `linkTables`, `minRenderWidth`, `HTMLAttributes` |

## Renderers

### renderers

`ChartRenderer[]` · Default `[]`

The Renderers a chart can be drawn with. See [Renderers](https://tiptap.dev/docs/diagrams/renderers/overview.md).

- Without one, charts show what [`unavailable`](https://tiptap.dev/docs/diagrams/api-reference/options.md#unavailable) returns.

### diagramRenderers

`DiagramRenderer[]` · Default `[]`

The Diagram Renderers a diagram can be drawn with. See [Diagrams](https://tiptap.dev/docs/diagrams/flow-diagrams/overview.md).

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

- Without one, diagrams show what [`unavailable`](https://tiptap.dev/docs/diagrams/api-reference/options.md#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](https://tiptap.dev/docs/diagrams/renderers/custom-chart-types.md).

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

### 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](https://tiptap.dev/docs/diagrams/charts/overview.md#importmermaidchart)**, 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.

```ts
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](https://tiptap.dev/docs/diagrams/api-reference/selectors.md#highlighted-source).
- **Your own source editor** can show the same with `highlightSource`. See
  [Text beside the picture](https://tiptap.dev/docs/diagrams/guides/split-view.md).

### styles

`ChartStyle[]` · Default `[]`

Styles a chart may name in `spec.style`, in addition to the built-in ones. See
[Styles](https://tiptap.dev/docs/diagrams/guides/styling.md#styles).

```ts
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](https://tiptap.dev/docs/diagrams/guides/styling.md#dark-color-scheme).

| Value     | Charts and diagrams are drawn                                                                                                                           |
| --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `'auto'`  | In the color scheme the page gives them: default colors turn dark when the page's `color-scheme` is dark, and follow the system when it is `light dark` |
| `'light'` | 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 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? }`:

| 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 reader; `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 reader open the data, return a button that reads the data when it is pressed: a chart's
with [`read`](https://tiptap.dev/docs/diagrams/api-reference/storage.md) or `readTable`, a diagram's source with `listDiagrams`. Here
`openDialog` stands for your own dialog; you could as well 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 its call does not pass `images`.

| Value      | Writes                                                                                                                                                                                                                               |
| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `'auto'`   | A chart as a Word chart, a `matrix` as a Word table. A picture for a chart type Word has no form for, or for a chart Word's own would show differently in what it says (see [Word](https://tiptap.dev/docs/diagrams/export.md#word)) |
| `'always'` | Every chart as a picture                                                                                                                                                                                                             |

### 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](https://tiptap.dev/docs/diagrams/api-reference/options.md#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](https://tiptap.dev/docs/diagrams/guides/collaboration.md).

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

```ts
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](https://tiptap.dev/docs/diagrams/data/chart-syntax.md#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.

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