---
title: "Formats"
description: "A diagram stores its source in one format, named by its format."
canonical_url: "https://tiptap.dev/docs/diagrams/flow-diagrams/formats"
---

# Formats

A diagram stores its source in one format, named by its format.

## The formats

| `format`    | Source                       | Drawn by                                                                                                                         |
| ----------- | ---------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| `'mermaid'` | Mermaid text                 | mermaid.js or Pele, see [Mermaid diagrams](https://tiptap.dev/docs/diagrams/flow-diagrams/formats.md#mermaid-diagrams)           |
| `'drawio'`  | draw\.io XML                 | The draw\.io Diagram Renderer, see [draw.io diagrams](https://tiptap.dev/docs/diagrams/flow-diagrams/formats.md#drawio-diagrams) |
| `'bpmn'`    | BPMN 2.0 XML with its layout | The BPMN Diagram Renderer, see [BPMN diagrams](https://tiptap.dev/docs/diagrams/flow-diagrams/formats.md#bpmn-diagrams)          |
| Another id  | Stored as it is              | A Diagram Renderer that lists it, see [Other formats](https://tiptap.dev/docs/diagrams/flow-diagrams/formats.md#other-formats)   |

## Mermaid diagrams

A diagram with `format: 'mermaid'` holds Mermaid text, stored as it is typed. Two Diagram
Renderers draw it; register one of them for `mermaid`, since the first that lists a format
draws it.

| Renderer                                                                                   | From                                     | Draws in                    | Picture                                                    |
| ------------------------------------------------------------------------------------------ | ---------------------------------------- | --------------------------- | ---------------------------------------------------------- |
| [`mermaidDiagramRenderer`](https://tiptap.dev/docs/diagrams/renderers/mermaid.md#diagrams) | `@tiptap-pro/extension-diagrams/mermaid` | A sandboxed iframe          | The Mermaid look                                           |
| [`peleDiagramRenderer`](https://tiptap.dev/docs/diagrams/renderers/pele.md)                | `@tiptap-pro/extension-diagrams/pele`    | A Web Worker, without a DOM | Pele's look: straight edges, about 8 times smaller to load |

```ts
editor.commands.insertFlowDiagram({ source: 'flowchart LR\n  A --> B', title: 'Order process' })
```

- **Source** starts with a Mermaid kind, such as `flowchart` or `sequenceDiagram`. Which kinds a
  diagram holds is under [Mermaid kinds](https://tiptap.dev/docs/diagrams/flow-diagrams/overview.md#mermaid-kinds).
- **The same source** draws with either Renderer, so switching changes the picture, never the
  document. See [Next to mermaid.js](https://tiptap.dev/docs/diagrams/renderers/pele.md#next-to-mermaidjs).
- **Pele also draws on a server**, for an export without a browser.
- **Pasting** Mermaid text, bare or in a ` ```mermaid ` fence, gives a Mermaid diagram.

## draw\.io diagrams

A diagram with `format: 'drawio'` holds draw\.io XML. It is drawn by the
[draw.io Diagram Renderer](https://tiptap.dev/docs/diagrams/renderers/drawio.md), which also connects the draw\.io
editor for changing it. Its page has a demo.

```ts
editor.commands.insertFlowDiagram({ source: drawioXml, format: 'drawio', title: 'Order process' })
```

- **Source** is an `<mxfile>` or a bare `<mxGraphModel>`.
- **Stored** as an `<mxfile>` whose pages are plain XML, so the stored text can be read and
  compared.
- **A bare model** becomes a file with one page.
- **A page draw\.io compressed** is uncompressed.
- **Anything else**, and source longer than 1,000,000 characters, makes `insertFlowDiagram` and
  `updateFlowDiagram` return `false`.
- **Pasting** draw\.io XML as text gives a draw\.io diagram.
- **Changing the format:** `updateFlowDiagram({ source, format })` changes it, for instance when
  a Mermaid diagram comes back from the draw\.io editor. A new format needs `source` in it.

## BPMN diagrams

A diagram with `format: 'bpmn'` holds BPMN 2.0 XML with its layout. It is drawn by the
[BPMN Diagram Renderer](https://tiptap.dev/docs/diagrams/renderers/bpmn.md), which also connects the bpmn-js modeler
for changing it. Its page has a demo.

```ts
editor.commands.insertFlowDiagram({ source: bpmnXml, format: 'bpmn', title: 'Payment check' })
```

- **Source** is `<definitions>` in the BPMN 2.0 model namespace.
- **Stored** as written.
- **Anything else**, and source longer than 1,000,000 characters, makes `insertFlowDiagram` and
  `updateFlowDiagram` return `false`.
- **Pasting** BPMN XML as text gives a BPMN diagram.

## Other formats

- **The id** is any id of letters, digits, `_` and `-`, up to 64 characters.
- **Accepted** by `insertFlowDiagram` and `updateFlowDiagram` when a registered Diagram
  Renderer lists it in `formats`.
- **Source** is stored as it is, up to 1,000,000 characters.
- **No Renderer draws it:** a document that holds such a format keeps it unchanged. The diagram
  shows what [`unavailable`](https://tiptap.dev/docs/diagrams/api-reference/options.md#unavailable) returns, and its source survives every
  save.