---
title: "Flow diagrams"
description: "A diagram shows steps, states or things and the links between them, such as a flowchart, a sequence diagram or a mind map."
canonical_url: "https://tiptap-docs.lin52025i.qzz.io/diagrams/flow-diagrams/overview"
---

# Flow diagrams

A diagram shows steps, states or things and the links between them, such as a flowchart, a sequence diagram or a mind map.

The `flowDiagram` node stores a diagram's text, called the source, in one of three formats:

- Mermaid text, for a flowchart, a sequence diagram, a Gantt chart, a mind map and
  [every other Mermaid kind](https://tiptap-docs.lin52025i.qzz.io/diagrams/flow-diagrams/overview.md#mermaid-kinds).
- draw\.io XML, for a diagram drawn with shapes in the draw\.io editor.
- BPMN XML, for a business process model.

## Quick start

Install the package and mermaid.js, the library that draws Mermaid diagrams. The example also
uses `@tiptap/core` and `@tiptap/starter-kit`. Install them too if your project does not have
them yet:

```bash
npm install @tiptap-pro/extension-diagrams mermaid
```

Then register a Diagram Renderer for Mermaid and insert a first diagram:

```ts
import { Editor } from '@tiptap/core'
import StarterKit from '@tiptap/starter-kit'
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({
  element: document.querySelector('#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](https://tiptap-docs.lin52025i.qzz.io/diagrams/renderers/overview.md) draws
charts. You pass it in the `diagramRenderers` option. [Mermaid](https://tiptap-docs.lin52025i.qzz.io/diagrams/renderers/mermaid.md#quick-start)
explains `mermaidUrl`, `rendererUrl` and the `?url` imports.

## More about diagrams

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

## Mermaid kinds

The first line of Mermaid source names its kind, such as `flowchart` or `sequenceDiagram`. A
Mermaid diagram can be any kind that Mermaid 11.17 knows, except five kinds that become
[charts](https://tiptap-docs.lin52025i.qzz.io/diagrams/flow-diagrams/overview.md#diagram-or-chart). `MERMAID_DIAGRAM_KINDS` lists the kinds, and
`mermaidDiagramKind(source)` returns the kind of a source.

| 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`, `architecture`                                              |
| `block`         | `block-beta`, `block`                                                            |
| `c4`            | `C4Context`, `C4Container`, `C4Component`, `C4Dynamic`, `C4Deployment`           |
| `requirement`   | `requirementDiagram`, `requirement`                                              |
| `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`                                                                  |

Both Diagram Renderers for Mermaid, mermaid.js and [Pele](https://tiptap-docs.lin52025i.qzz.io/diagrams/renderers/pele.md#next-to-mermaidjs),
draw every kind in this list. For a kind that no registered Diagram Renderer draws, see
[Which Renderer draws a diagram](https://tiptap-docs.lin52025i.qzz.io/diagrams/renderers/custom-diagrams.md#which-renderer-draws-a-diagram).
[Editing in the diagram](https://tiptap-docs.lin52025i.qzz.io/diagrams/flow-diagrams/editing.md) lists the kinds whose text you can change in the diagram.

## Diagram or chart

Mermaid `pie`, `xychart`, `sankey`, `radar` and `treemap` become a `chart` node with data you can
edit, see [`importMermaidChart`](https://tiptap-docs.lin52025i.qzz.io/diagrams/charts/overview.md#importmermaidchart). Every other kind in
[the list](https://tiptap-docs.lin52025i.qzz.io/diagrams/flow-diagrams/overview.md#mermaid-kinds) becomes a diagram. [`insertFlowDiagram`](https://tiptap-docs.lin52025i.qzz.io/diagrams/flow-diagrams/overview.md#insertflowdiagram) and
[`updateFlowDiagram`](https://tiptap-docs.lin52025i.qzz.io/diagrams/flow-diagrams/overview.md#updateflowdiagram) refuse chart source.

## 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 drawn diagram, `'code'` shows 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-docs.lin52025i.qzz.io/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-docs.lin52025i.qzz.io/diagrams/flow-diagrams/editing.md#moving-shapes) |

The document never stores the drawn diagram, its size on screen or its loading state.

### Source is data

The source never runs as code in your app's web page. When a diagram is written, the extension
removes `%%{init: …}%%` directives and the frontmatter block, so a document cannot
change how Mermaid runs. A `title` in the frontmatter becomes the diagram's title, unless you give one. The colors come
from your page's CSS, not from the source.

### In HTML and plain text

In HTML, a diagram is a `<figure data-type="flow-diagram">`. It holds its source in
`<pre><code class="language-mermaid">` and its title in a `<figcaption>`. A draw\.io diagram uses
`language-drawio`, and a BPMN diagram uses `language-bpmn`.

An HTML or Markdown export made without the extension keeps the source as a code block. If you
paste that HTML into an editor that has the extension, you get the diagram back.

As plain text, a Mermaid diagram is `[diagram: title]` followed by its source. A diagram in any
other format is only `[diagram: title]`, or `[diagram]` without a title.

## Changing a diagram

You change a diagram with a [command](https://tiptap-docs.lin52025i.qzz.io/diagrams/flow-diagrams/overview.md#commands):

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

A form of your own can call `updateFlowDiagram` on every input, while someone types. Each call is
one undo step.

The diagram is drawn again after every change. When a drawing finishes after a newer change, it
is dropped. Mermaid source with a syntax error shows the error state and its message until the
source is valid again.

### Diagram or source for every diagram

Each diagram has its own view. To switch them all at once, as the Mermaid demo does, chain
`setFlowDiagramView` for every diagram:

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

## Listing, zooming and exporting diagrams

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

`setZoom`, `getZoom`, `setMaximized` and `getMaximized` take a diagram's position, as they take a
chart's. See [Size and view](https://tiptap-docs.lin52025i.qzz.io/diagrams/guides/size-and-view.md).

### Export

`export({ pos })`, `exportAll()` and `exportDocx()` include diagrams as they include charts. In
Word, a diagram is a PNG image. [Export](https://tiptap-docs.lin52025i.qzz.io/diagrams/export.md) has the options and what comes back.

The mermaid.js, draw\.io and BPMN Diagram Renderers draw only in a browser. On a server, `export`
throws for a diagram, and `exportDocx` leaves the diagram out with a note. Pele's
[`renderPeleDiagram`](https://tiptap-docs.lin52025i.qzz.io/diagrams/renderers/pele.md#on-a-server) can still draw Mermaid source 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](https://tiptap-docs.lin52025i.qzz.io/diagrams/data/pasting.md) diagram source
runs this command.

Returns `false` for Mermaid chart source (`pie`, `xychart`, `sankey`, `radar`, `treemap`), for a
kind not in [the list](https://tiptap-docs.lin52025i.qzz.io/diagrams/flow-diagrams/overview.md#mermaid-kinds), such as `zenuml`, 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 you leave 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` and changes nothing when the new source is not a kind that is drawn in the
diagram's format, or when `format` changes without `source`.

### setFlowDiagramView

Shows the drawn diagram or its source.

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

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

The view is stored in the document, so everyone who opens the document sees the same view.

### convertCodeBlockToDiagram

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

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

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

Mod-Enter in the code block runs it too, see
[Mod-Enter in a code block](https://tiptap-docs.lin52025i.qzz.io/diagrams/data/quick-input.md#mod-enter-in-a-code-block).

Returns `false` for a code block that holds chart source or anything that is not a Mermaid
diagram.