Manual: The Insert / Edit Mermaid dialog and the Mermaid group

[alderg]

draw.io can turn Mermaid text into native, fully editable draw.io shapes. This guide explains the Insert / Edit Mermaid dialog, the list of supported diagram types, and — in detail — the special group that wraps every Mermaid diagram (its icons, how to select and move it, its transparent size, the lock and edit icons, and where the Mermaid source is kept).

---

Opening the dialog

Use Insert (+) ▸ Mermaid… in the toolbar/menu. A dialog opens with:

• a type selector (Mermaid / PlantUML),
• a large text area where you paste or type your Mermaid source (you can also drag a text file onto it),
• a help (?) icon that links to this guide,
• Insert and Close buttons.

Paste your Mermaid code and press Insert. draw.io parses the text and drops the result onto the canvas as real draw.io cells — not a picture.

---

Supported diagram types

The diagram type is detected from the first keyword of your source, so the text must start with one of the keywords below (optional YAML front‑matter, %%{init}%% directives and comments are skipped first).

Diagram	Start your source with
Flowchart	flowchart or graph
Class diagram	classDiagram
State diagram	stateDiagram / stateDiagram-v2
Sequence diagram	sequenceDiagram
ZenUML sequence	zenuml
Entity‑Relationship (ER)	erDiagram
Requirement diagram	requirementDiagram
C4 model	C4Context / C4Container / C4Component / C4Dynamic / C4Deployment
Gantt chart	gantt
User journey	journey
Kanban board	kanban
Timeline	timeline
Git graph	gitGraph
Pie chart	pie
XY chart (bar / line)	xychart-beta
Quadrant chart	quadrantChart
Radar chart	radar / radar-beta
Sankey diagram	sankey / sankey-beta
Treemap	treemap / treemap-beta
Mindmap	mindmap
Block diagram	block / block-beta
Packet diagram	packet / packet-beta
Architecture diagram	architecture / architecture-beta
Venn diagram	venn
Ishikawa / fishbone	ishikawa or fishbone
Tree view	treeView
Wardley map	wardley / wardley-beta
Event Modeling	eventmodeling / eventmodeling-beta

If the text starts with a keyword that isn't in this list, draw.io reports it as an unsupported diagram type. If it is a supported type but the body can't be parsed, you get a parse error pointing at the problem.

---

Choosing the layout engine (ELK)

The graph‑based diagram types — flowchart, class, state, entity‑relationship and requirement — are arranged by a layout engine. By default draw.io uses Dagre (the same engine Mermaid uses internally), but you can switch these diagrams to the ELK engine, which often gives tidier orthogonal routing and tighter layer spacing on large or deeply‑nested graphs.

You request ELK with standard Mermaid configuration placed at the top of your source. There are two ways:

1. Flowcharts — the defaultRenderer knob

%%{init: {"flowchart": {"defaultRenderer": "elk"}} }%%
flowchart LR
  A --> B --> C

2. Any graph type — the layout key

As an init directive:

%%{init: {"layout": "elk"}}%%
classDiagram
  Animal <|-- Dog

…or as YAML front‑matter:

---
config:
  layout: elk
---
flowchart LR
  A --> B --> C

Notes:

• The setting only affects the five graph‑based types above. The other diagram types (sequence, gantt, sankey, mindmap, etc.) use their own dedicated layouts and ignore it.
• If ELK isn't available in your environment — or it can't lay out a particular graph — draw.io automatically falls back to Dagre so the diagram still renders.

---

The Mermaid group

Whatever the diagram type, the inserted result is always placed inside one special group cell that wraps all the generated shapes. Understanding this group is the key to working with Mermaid output.

Its size is "transparent"

The group has no fill and no border — it is completely see‑through. Its selection outline simply hugs the generated shapes with a small uniform margin (about 20 px) around them; there is no solid rectangle drawn on top of your diagram.

Because the bounds are transparent, only the actual shapes inside are clickable — clicking the empty margin around them clicks straight through to whatever is behind. The group itself stores no fixed width/height; its extent is derived from its contents, so it always grows and shrinks to fit the diagram.

The three corner icons

Select the group and three small icons appear at its top‑left corner, arranged in an L‑shape (the lock sits above the move icon in the corner column, with the pen to their right):

Icon	What it does
✛ Move	Drag this to move the whole diagram as a single unit. Because the group is transparent there is no body to grab, so this handle is how you reposition everything at once without disturbing the individual shapes.
🔓 / 🔒 Lock / unlock	Toggles whether the group behaves as one locked block (see below). It shows an open padlock when unlocked (the default) and a closed padlock when locked.
✎ Edit (pen)	Re‑opens the Mermaid editor with the stored source so you can change the text and regenerate the diagram.

Selecting the group vs. the shapes inside

By default the group is unlocked, which keeps every generated shape individually selectable:

• Select a single shape — just click it. You can restyle, relabel, resize or move individual shapes freely, exactly like any other draw.io cell.
• Select the whole group — click the move icon, or click an already‑selected shape a second time to step "out" to the surrounding group, or lock the group (see below) so any click grabs the whole thing.

Moving the group as a whole

Drag the move icon, or first select the group (as above) and then drag it. Every shape moves together and their relative positions are preserved. Dragging an individual shape (while unlocked) moves only that shape.

The lock icon

Click the padlock to lock the group. While locked:

• Clicking any shape inside selects the entire group instead of the single shape — handy once you're done editing and just want to treat the diagram as one object you can't disturb by accident.
• Double‑clicking anywhere on a locked group opens the Mermaid editor (same as the pen icon).

Click the padlock again to unlock and get back to selecting and editing individual shapes.

The edit icon — and where the Mermaid code is stored

The Mermaid source you typed is saved on the group itself, as a mermaidData attribute on the group cell. Because it's part of the cell, it is written into your .drawio file and travels with the diagram — so the diagram stays re‑editable as Mermaid even after saving, closing and reopening, and even after you share the file.

The attribute holds a small JSON object with two parts — the data (your Mermaid source) and an optional config (a Mermaid configuration object, or null):

• Diagrams you insert now are stored with config: null — no custom configuration, so draw.io's built‑in default Mermaid settings are applied every time the source is parsed.
• Legacy diagrams (the older Mermaid cells that were stored as a static image) were originally rendered with a different, older configuration — a neutral theme plus specific sequence‑ and Gantt‑diagram spacing. When such a cell is upgraded to an editable group (on first double‑click), draw.io re‑parses it with that legacy configuration so the new shapes match the original image, and copies that configuration into the new group's mermaidData. So a migrated diagram keeps a non‑null config, whereas a freshly inserted one has none.

You normally never need to touch the config, but if you do (for example to force a theme or tweak spacing), it can be edited by hand: right‑click the group ▸ Edit Data… and edit the mermaidData value. Changing the config object there — or clearing it back to the default — takes effect the next time the source is parsed. Note that editing the data in this dialog only changes the stored text; use the pen icon to actually re‑render the shapes.

To edit the source, click the pen (edit) icon (or double‑click a locked group). The stored source opens in a text editor; change it and confirm, and draw.io re‑parses the text and rebuilds the shapes inside the same group.

What survives when you re‑edit the source

Re‑editing the Mermaid text re‑runs the parser and lays the diagram out again from scratch, then re‑applies your per‑shape edits on top. The rule of thumb: appearance is kept, position is not.

Kept — re‑applied to each regenerated shape (matched by identity, as long as that node still exists in the new source):

• Style changes on individual shapes — fill/background colour, line/stroke colour and style, font colour and formatting, rounded corners, opacity, and so on. Both changes and removals are remembered: a colour you set overrides the regenerated default, and a style key you cleared stays cleared.
• Manual relabels — if you renamed a shape on the canvas, that text is kept.

Not kept — always taken fresh from the new parse and layout:

• Geometry — position and size. The diagram is laid out again, so shapes you dragged to a new spot or resized by hand return to the layout's coordinates. (Re‑positioning is the whole point of regenerating, so this is by design.)
• Edge routing and connection points — waypoints and which side an arrow attaches to are owned by the layout and recomputed every time.
• Shapes you added or deleted by hand, and any edits to a node that no longer exists in the new source — the group's contents are rebuilt from the text, so anything without a counterpart in the new source is gone.

In short: style your shapes freely and the styling follows them across edits — but treat layout (positions, sizes, routing) as Mermaid's, and change it through the source rather than by hand if you plan to keep editing the source.

Legacy diagrams: older draw.io files stored Mermaid output as a static image. Those still open as plain images and are upgraded to an editable group automatically the first time you double‑click them, after which everything above applies.