---
title: "Flow diagrams"
description: "A diagram is a picture of a graph or a process."
canonical_url: "https://tiptap.dev/docs/diagrams/flow-diagrams/overview"
---

# Flow diagrams

A diagram is a picture of a graph or a process.

## Quick start

```ts
import { Diagrams, chartStyleRules, flowDiagramStyleRules } from '@tiptap-pro/extension-diagrams'
import { mermaidDiagramRenderer } from '@tiptap-pro/extension-diagrams/mermaid'
import rendererUrl from '@tiptap-pro/extension-diagrams/mermaid-renderer?url&no-inline'
import mermaidUrl from 'mermaid/dist/mermaid.min.js?url'

const style = document.createElement('style')
style.textContent = chartStyleRules() + flowDiagramStyleRules()
document.head.append(style)

const editor = new Editor({
  extensions: [
    StarterKit,
    Diagrams.configure({
      diagramRenderers: [mermaidDiagramRenderer({ mermaidUrl, rendererUrl })],
    }),
  ],
})

editor.commands.insertFlowDiagram({
  source: 'flowchart LR\n  A[Order] --> B{Paid?}\n  B -->|yes| C[Ship]',
  title: 'How an order moves',
})
```

- A Diagram Renderer draws diagrams with one library, as a Renderer draws charts.
- Mermaid draws in a sandboxed iframe. `mermaidUrl` and `rendererUrl` are the two files it loads.
- The `?url` imports are Vite's. With another bundler, serve both files and pass their URLs.
- The Mermaid charts and diagrams share one iframe. See [Mermaid](https://tiptap.dev/docs/diagrams/renderers/mermaid.md).

## More about diagrams

| Page                                                                                      | Covers                                                         |
| ----------------------------------------------------------------------------------------- | -------------------------------------------------------------- |
| [Formats](https://tiptap.dev/docs/diagrams/flow-diagrams/formats.md)                      | Mermaid, draw\.io, BPMN and formats of your own                |
| [Editing in the picture](https://tiptap.dev/docs/diagrams/flow-diagrams/editing.md)       | Changing a text by a double click, moving a flowchart's shapes |
| [A diagram from a table](https://tiptap.dev/docs/diagrams/flow-diagrams/from-table.md)    | A flowchart drawn from a table, one row per step               |
| [Renderers](https://tiptap.dev/docs/diagrams/renderers/overview.md#which-renderer-to-use) | Mermaid, Pele, draw\.io and BPMN, and what each one draws      |

## Mermaid kinds

A Mermaid diagram holds any kind Mermaid 11.17 knows, except the five that are
[charts](https://tiptap.dev/docs/diagrams/flow-diagrams/overview.md#diagram-or-chart). The first line names it. `MERMAID_DIAGRAM_KINDS` lists them, and
`mermaidDiagramKind(source)` reads the kind.

| Kind            | First line                                                                       |
| --------------- | -------------------------------------------------------------------------------- |
| `flowchart`     | `flowchart`, `graph`                                                             |
| `sequence`      | `sequenceDiagram`                                                                |
| `state`         | `stateDiagram-v2`, `stateDiagram`                                                |
| `class`         | `classDiagram`, `classDiagram-v2`                                                |
| `er`            | `erDiagram`                                                                      |
| `journey`       | `journey`                                                                        |
| `gantt`         | `gantt`                                                                          |
| `mindmap`       | `mindmap`                                                                        |
| `timeline`      | `timeline`                                                                       |
| `quadrant`      | `quadrantChart`                                                                  |
| `git`           | `gitGraph`                                                                       |
| `kanban`        | `kanban`                                                                         |
| `architecture`  | `architecture-beta`                                                              |
| `block`         | `block-beta`, `block`                                                            |
| `c4`            | `C4Context`, `C4Container`, `C4Component`, `C4Dynamic`, `C4Deployment`           |
| `requirement`   | `requirementDiagram`                                                             |
| `packet`        | `packet-beta`, `packet`                                                          |
| `venn`          | `venn-beta`                                                                      |
| `ishikawa`      | `ishikawa-beta`, `ishikawa`                                                      |
| `treeView`      | `treeView-beta`                                                                  |
| `wardley`       | `wardley-beta`                                                                   |
| `cynefin`       | `cynefin-beta`                                                                   |
| `swimlane`      | `swimlane-beta`                                                                  |
| `railroad`      | `railroad-beta`, `railroad-ebnf-beta`, `railroad-abnf-beta`, `railroad-peg-beta` |
| `eventModeling` | `eventmodeling`                                                                  |

- **Which kinds a picture shows** is up to the Diagram Renderer. The Mermaid and the Pele
  Renderer draw every kind in the list.
- **A kind no registered Renderer draws** shows what [`unavailable`](https://tiptap.dev/docs/diagrams/api-reference/options.md#unavailable)
  returns, with the reason `'unsupported-kind'`. Its source stays in the document.
- **Editing in the picture** works in the kinds listed in [Editing in the picture](https://tiptap.dev/docs/diagrams/flow-diagrams/editing.md).
  The others are only shown.

## Diagram or chart

- **Mermaid `pie`, `xychart`, `sankey`, `radar` and `treemap`** are charts. They become a
  `chart` with data you can edit; see [`importMermaidChart`](https://tiptap.dev/docs/diagrams/charts/overview.md#importmermaidchart).
- **Every other kind** in [the list](https://tiptap.dev/docs/diagrams/flow-diagrams/overview.md#mermaid-kinds) becomes a diagram.
- **Chart source, and a kind not in that list** such as `zenuml`, make `insertFlowDiagram` and
  `updateFlowDiagram` return `false`.
- **Empty source** is allowed, for a diagram still to be written.

## How a diagram is stored

| Attribute     | Content                                                                          |
| ------------- | -------------------------------------------------------------------------------- |
| `format`      | `'mermaid'`, `'drawio'`, `'bpmn'` or the id of a format a Diagram Renderer draws |
| `source`      | The Mermaid text, at most 50,000 characters, or the XML                          |
| `title`       | Shown as a caption below the diagram, or `null`                                  |
| `description` | Alt text and accessible description, or `null`                                   |
| `view`        | `'diagram'` shows the picture, `'code'` the source                               |
| `options`     | Settings beyond the source, in the table below. Anything else is kept as it is   |

| Key in `options` | Content                                                                                                                   |
| ---------------- | ------------------------------------------------------------------------------------------------------------------------- |
| `size`           | The diagram's size, see [setDiagramSize](https://tiptap.dev/docs/diagrams/guides/size-and-view.md#setdiagramsize)         |
| `link`           | The table the diagram is drawn from                                                                                       |
| `positions`      | The offsets of moved shapes, see [Moving shapes](https://tiptap.dev/docs/diagrams/flow-diagrams/editing.md#moving-shapes) |

The picture, its size and its loading state are never stored.

### Source is data

- The source is data, never code that runs in the page.
- `%%{init: …}%%` directives are removed when a diagram is written.
- The `config` of a frontmatter block is removed too, so a document cannot change how Mermaid
  runs.
- A `title` in the frontmatter becomes the diagram's title, unless one is given.
- The colors come from the page, not from the source.

### In HTML and plain text

- **HTML:** a diagram is a `<figure data-type="flow-diagram">`. It holds its source in
  `<pre><code class="language-mermaid">` (`language-drawio` for draw\.io, `language-bpmn` for
  BPMN) and its title as `<figcaption>`.
- **Plain text:** a diagram that is not Mermaid is only its title.
- **Export without the Extension:** an HTML or Markdown export keeps the source as a code block.
- **Pasting that HTML** into an editor with the Extension gives the diagram back.

## Changing a diagram

Every change is a Command, see [Commands](https://tiptap.dev/docs/diagrams/flow-diagrams/overview.md#commands).

```ts
editor.commands.updateFlowDiagram({ source: 'sequenceDiagram\n  A->>B: Hello' })
editor.commands.setFlowDiagramView({ view: 'code' })
```

- **Writing while someone types:** a form can call `updateFlowDiagram` on every input. Each call
  is one undo step.
- **Redrawing:** the picture is drawn again for every change.
- **A drawing that finishes after a newer change** is dropped.
- **Mermaid source with a syntax error** shows the error state and its message until the source
  is valid again.

### Picture or source for every diagram

The view belongs to each diagram. For one switch over the whole document, as in the Mermaid
demo, call `setFlowDiagramView` for every diagram in one chain:

```ts
const chain = editor.chain()
for (const { pos } of editor.storage.diagrams.listDiagrams()) {
  chain.setFlowDiagramView({ pos, view: 'code' })
}
chain.run()
```

## Readers, zoom and export

### Listing diagrams

`editor.storage.diagrams.listDiagrams()` returns every diagram with:

| Field      | Content                                                                                           |
| ---------- | ------------------------------------------------------------------------------------------------- |
| `pos`      | Its position                                                                                      |
| Attributes | Its attributes                                                                                    |
| `kind`     | The kind of Mermaid diagram, or `null` when the source is empty, not a kind that is drawn, or XML |
| `drawable` | Whether a Diagram Renderer for its format can draw the source                                     |

### Zoom and maximize

Zoom and maximize work on a diagram as on a chart: `setZoom`, `getZoom`, `setMaximized` and
`getMaximized` take its position.

### Export

Diagrams are exported like charts; [Export](https://tiptap.dev/docs/diagrams/export.md) has the options and what comes back.

- **`export({ pos })`** draws a diagram as SVG, PNG, WebP or JPEG.
- **`exportAll()`** includes diagrams, in document order.
- **`exportDocx()`** places a diagram in the Word document as a PNG picture with its title as
  caption, between the native charts. It adds a note to `notes` that it is a picture there.
- **On a server:** the mermaid.js, draw\.io and BPMN Diagram Renderers draw only in a browser.
  `export` throws for a diagram, and `exportDocx` leaves it out with a note. Mermaid source can
  still be drawn there with Pele's [`renderPeleDiagram`](https://tiptap.dev/docs/diagrams/renderers/pele.md#on-a-server).

## Commands

### insertFlowDiagram

Inserts a diagram at the selection, or at `pos`, and selects it unless `select` is `false`.

```ts
editor.commands.insertFlowDiagram({
  source: 'flowchart LR\n  order[Order placed] --> ship[Shipped]',
  title: 'Order flow',
})
```

| Option        | Type             | Description                                                                                                          |
| ------------- | ---------------- | -------------------------------------------------------------------------------------------------------------------- |
| `source`      | `string`         | Mermaid source, draw\.io XML with `format: 'drawio'`, or BPMN 2.0 XML with `format: 'bpmn'`. Empty source is allowed |
| `format`      | `string`         | `'mermaid'` (default), `'drawio'`, `'bpmn'`, or another format when a registered Diagram Renderer lists it           |
| `title`       | `string \| null` | The diagram's title                                                                                                  |
| `description` | `string \| null` | Alt text and accessible description                                                                                  |
| `pos`         | `number`         | The position to insert at. Defaults to the selection                                                                 |
| `select`      | `boolean`        | `false` leaves the selection where it is. Default `true`                                                             |

- An empty paragraph at the selection is replaced.
- Pasting Mermaid diagram source, draw\.io XML or BPMN XML calls it.

Returns `false` for Mermaid chart source (`pie`, `xychart`, `sankey`, `radar`, `treemap`), for a
kind not in [the list](https://tiptap.dev/docs/diagrams/flow-diagrams/overview.md#mermaid-kinds), and,
with `format: 'drawio'` or `'bpmn'`, for source that is not that XML.

### updateFlowDiagram

Changes the source, the format, the title or the description of the selected diagram, or the one
at `pos`. A field left out keeps its value.

```ts
editor.commands.updateFlowDiagram({ title: 'Order flow, revised' })
```

| Option        | Type             | Description                                                                                           |
| ------------- | ---------------- | ----------------------------------------------------------------------------------------------------- |
| `source`      | `string`         | The new source. On a diagram drawn from a table, the diagram keeps it and no longer follows the table |
| `format`      | `string`         | The new format. Needs `source` in that format                                                         |
| `title`       | `string \| null` | The new title. `null` removes it                                                                      |
| `description` | `string \| null` | The new description. `null` removes it                                                                |
| `pos`         | `number`         | The diagram's position. Defaults to the selected diagram                                              |

Returns `false` when the new source is not a kind that is drawn in the diagram's format, or when
`format` changes without `source`, and then changes nothing.

### setFlowDiagramView

Shows the picture or the source of a diagram.

```ts
editor.commands.setFlowDiagramView({ view: 'code' })
```

| Option | Type                  | Description                                              |
| ------ | --------------------- | -------------------------------------------------------- |
| `view` | `'diagram' \| 'code'` | `'diagram'` shows the picture, `'code'` the source       |
| `pos`  | `number`              | The diagram's position. Defaults to the selected diagram |

The view is stored, so every reader of the document sees the same.

### convertCodeBlockToDiagram

Replaces the code block at the selection, or at `pos`, with a diagram of its Mermaid source and
selects it.

```ts
if (editor.can().convertCodeBlockToDiagram()) editor.commands.convertCodeBlockToDiagram()
```

| Option | Type     | Description                                                 |
| ------ | -------- | ----------------------------------------------------------- |
| `pos`  | `number` | A position inside the code block. Defaults to the selection |

- `editor.can().convertCodeBlockToDiagram()` says whether to offer it.
- Mod-Enter in the code block runs it too, unless
  [`codeBlockShortcut`](https://tiptap.dev/docs/diagrams/api-reference/options.md#codeblockshortcut) says otherwise.

Returns `false` for a code block holding chart source or anything else.