Mermaid Flowcharts (with UML Meanings)

Mermaid Flowcharts (with UML Meanings)

Beginner‑friendly guide with short explanations and many examples.

---

1) What is Mermaid Flowchart?

A flowchart is a diagram made of nodes (shapes with text) connected by edges (lines/arrows). Mermaid lets you write text that renders into a diagram. Mermaid Flowchart ≠ UML: Mermaid is a diagram tool; UML is a modeling standard. In this guide we show the closest UML ideas for each Mermaid feature. (Mermaid)

---

2) Quick start (minimal example)

flowchart TD
  Start([Start]) --> Check{In stock?}
  Check -->|Yes| Ship[Ship order]
  Check -->|No| Backorder[Backorder]

What it shows: A top‑down flow with one decision and two outcomes.

---

3) Directions and graph keyword

Use flowchart (or its alias graph) plus a direction:

• TB / TD = top‑down
• BT = bottom‑up
• LR = left‑to‑right
• RL = right‑to‑left

Direction changes layout only (no UML meaning). (Mermaid)

TD example

flowchart TD
  A[Start] --> B[Step] --> C[End]

What it shows: A vertical (top‑down) layout.

LR example

flowchart LR
  A[Start] --> B[Step] --> C[End]

What it shows: A horizontal (left‑to‑right) layout.

---

4) Nodes: ids, labels, text

• Id vs label: A[Text] creates node id A with label Text. You can set label once and reuse id later.
• Unicode/markdown in labels: put the label in double quotes, and markdown (bold/italic) works in labels.
• Escape special characters either by quoting ("...") or using HTML entities like ", <, #. (Mermaid)

flowchart LR
  A["Hello **world** and *friends*"] --> B["Unicode: “Привет”"]
  C["Quote: "Hi", less-than: <, hash: #"]

What it shows: Ids, markdown in labels, and escaped characters.

Gotchas

• Using the lowercase word end as a node label breaks parsing. Use End or END instead. (Mermaid)
• If a node id starts with o or x right after a link operator (e.g., A---oB), Mermaid may think you want a circle or cross edge. Add a space (A--- oB) or capitalize (A---OB). (Mermaid)

---

5) Shapes (classic bracket syntax)

Mermaid Syntax	Visual Shape (name)	Typical Flowchart Role	Closest UML Meaning	Example
A[Text]	Rectangle	Process/step	Action (UML Activity uses rounded rectangles; this is a near match)	A[Process step]
A(Text)	Rounded rectangle	Process/step	Action (best visual match)	A(Start job)
A([Text])	Stadium / terminator	Start/End in flowcharts	No direct UML; UML start/end use circles	A([Begin])
A[[Text]]	Subroutine / double-rect	Subprocess	Call Behavior Action (sub‑activity)	A[[Recalculate total]]
A[(Text)]	Cylinder (database)	Data store	DataStoreNode / Object Node	A[(Orders DB)]
A((Text))	Circle	Connector/terminator in flowcharts	Initial node (if filled) or junction; style may be needed	A((Start))
A(((Text)))	Double circle	End/terminator	Activity final node	A(((End)))
A{Text}	Diamond (rhombus)	Decision	Decision / Merge node	A{In stock?}
A{{Text}}	Hexagon	Preparation / condition	No standard UML; use an Action with note/stereotype	A{{Prepare}}
A>Text]	Asymmetric	Off‑page link / special step	No standard UML	A>Go to page 2]
A[/Text/]	Parallelogram	Input/Output	Often modeled as Object node or specific Action (e.g., accept input)	A[/User input/]
A[\Text\]	Parallelogram alt	Input/Output	Same as above	A[\Show result\]
A[/Text\]	Trapezoid	Manual operation (base bottom/top varies)	No standard UML; use Action with «manual» stereotype	A[/Manual step\]
A[\Text/]	Trapezoid alt	Manual operation (alt)	Same as above	A[\Manual step/]

Note: the asymmetric shape currently has only one orientation (no mirrored form). (Mermaid)

flowchart LR
  R[Rect] --> RR(Rounded)
  ST([Terminator]) --> D{Decision}
  DB[(DB)] --> C((Circle)) --> CC(((End)))
  HEX{{Prepare}} --> S>Asymmetric]
  IN[/Input/] --> OUT[\Output\]
  M[/Manual\] --> M2[\Manual/]
  SUB[[Subroutine]] --> R

What it shows: A sampler of classic shapes connected in one flow. (Mermaid)

Reminder: These are flowchart symbols. UML Activity Diagrams mainly use Actions (rounded rectangles), Decisions (diamonds), Initial (filled circle), Final (bullseye), and Fork/Join bars. When a flowchart shape has no exact UML meaning, use an Action plus a note/stereotype, or an Object Node.

---

6) Expanded shapes (v11.3+)

Mermaid v11.3+ adds a general way to assign shapes:

• Generic assignment: A@{ shape: rect }
• Many new shapes are available, e.g.:
  • circle (Start) → UML Initial node
  • dbl-circ (Stop) → UML Activity final
  • hex (Prepare) → No standard UML; use Action + stereotype
  • fork (Fork/Join bar) → UML Fork/Join
  • cyl (Database) → UML DataStoreNode/Object Node
  • doc (Document) → Usually Object Node or Action
  • text (Text block) → No UML semantics (note-like) (Full list in docs; feature tag v11.3.0+.) (Mermaid)

flowchart LR
  S@{ shape: circle, label: "Start" } --> P@{ shape: rect, label: "Process" }
  P --> F@{ shape: fork, label: "Fork/Join" } --> E@{ shape: dbl-circ, label: "Stop" }

What it shows: New shape syntax mixed with classic flow.

---

7) Edges (links) and labels

Edge Syntax	Meaning	Closest UML Meaning	Example
A --> B	Directed edge with arrow	Control flow	A --> B
A --- B	Open line (no arrow)	No standard in UML Activity	A --- B
A -.-> B	Dotted arrow	Not standard in UML Activity (dashed lines mean dependency elsewhere)	A -.-> B
A ==> B	Thick arrow	Style only, no UML semantics	A ==> B
A -- text --> B or A --> | text | B	Labeled edge	UML guards like [x > 0]	Check --> | Yes | Ship
A o--o B, B <--> C, C x--x D	Circle/cross heads, both‑ways	No standard UML meaning	A o--o B
A ~~~ B	Invisible link (layout only)	No UML meaning	A ~~~ B
a --> b & c --> d	Chaining / parallel link syntax	Convenience only	a --> b & c --> d
Extra dashes (---->, ===>, -..->)	Longer rank spacing	Layout only	B ----> E

Mermaid supports all of the above, plus link lengthening using extra dashes/equal/dot characters and multi‑directional arrows. (Mermaid)

flowchart LR
  Start([Start]) --> Q{Approved?}
  Q -->|Yes| Go[Proceed]
  Q ---->|No| Fix[Fix and retry]

What it shows: Yes/No labels and “extra dashes” to push the No edge further. (Mermaid)

---

8) Subgraphs (groups)

You can group nodes with subgraph ... end. You can connect edges to and from subgraphs. You can also set a direction inside a subgraph. Limitation: if any node in a subgraph links outside, the subgraph’s direction is ignored and it inherits the parent direction. (Mermaid)

flowchart LR
  subgraph Fulfillment
    direction TB
    Pick[Pick items] --> Pack[Pack box]
  end

  Order([Order]) --> Fulfillment
  Pack --> Ship[Ship]

  %% Because Pack links to Ship (outside), the TB direction inside
  %% may be ignored and Fulfillment will inherit LR from the parent.

What it shows: A subgraph with internal direction and edges to/from outside; demonstrates the direction limitation.

---

9) Styling and classes

• Single node: style nodeId fill:#fee,stroke:#c33,stroke-width:2px,color:#900
• Classes: classDef warn fill:#fff3cd,stroke:#856404; then class X warn; (or attach with :::).
• Links: linkStyle N ... (use link number(s) or default) to style links.
• Curves: set curve types like cardinal, stepBefore, etc., for all edges via config; per‑edge curve is possible when the edge has an ID (v11.10+). (Mermaid)

%% Diagram-level curve style via directive
---
config:
  flowchart:
    curve: stepBefore
---
flowchart LR
  A[Start] --> B[Warned edge] --> C[End]
  style C fill:#e6ffed,stroke:#1f883d
  classDef warn fill:#fff3cd,stroke:#856404
  class B warn
  linkStyle 1 stroke:#555,stroke-width:3px

What it shows: A custom node color, a class, a styled link, and a diagram‑level curve. (Edge‑level curves require Edge IDs, v11.10+.) (Mermaid)

---

10) Interaction (click)

You can make nodes clickable—either call a JS callback or go to a URL. This works when Mermaid’s securityLevel is loose (not strict). (Mermaid)

flowchart LR
  Home[Home] --> Repo[Repo]
  click Home "https://example.com" "Go home"
  click Repo href "https://github.com" "_blank"
  %% For callbacks (requires securityLevel: 'loose'):
  %% click Home callback "Tooltip text"

What it shows: Clickable nodes (URL and callback).

---

11) Icons & images (v11.3+/v11.7+)

• Special shapes (v11.3+): icon and image are built‑in node shapes.
• Font Awesome support: You can use FA icons; registering icon packs is v11.7+, or include FA CSS. (Mermaid)

flowchart TD
  I@{ shape: icon, icon: "fa:fa-user", form: "circle", label: "User", pos: "b", h: 48 }
  L@{ shape: image, img: "https://example.com/logo.png", label: "Logo", pos: "t", h: 48, constraint: "on" }
  I --> L

What it shows: An icon node and an image node connected. (Icons need FA CSS or a registered pack; see docs.) (Mermaid)

---

12) Common pitfalls (quick list)

• Lowercase end as a node breaks flowcharts; write End or END. (Mermaid)
• Leading o / x after a link operator can be parsed as circle/cross edge heads—add a space or capitalize. (Mermaid)
• Special characters: quote or escape with entities (e.g., ", <, #). (Mermaid)
• Subgraph direction limitation: links to outside make the subgraph inherit the parent’s direction. (Mermaid)

flowchart LR
  %% Bad (would become a circle head):  Dev --- oPs
  %% Good (space or capital):
  Dev --- Ops

What it shows: The spacing/capitalization workaround for o/x.

---

13) UML mapping cheat sheet (compact)

Mermaid (Flowchart)	UML Activity meaning
Rounded rectangle	Action
Diamond	Decision / Merge
Filled circle	Initial node
Double circle (bullseye)	Activity final node
Thick bar (fork shape)	Fork/Join (bar)
Cylinder	DataStoreNode / Object Node
Parallelogram (I/O)	Usually Action with «input»/«output», or Object Node
Stadium / Asymmetric / Trapezoid	No standard UML; use Action + note/stereotype

flowchart LR
  I@{ shape: circle, label: "Initial" } --> A(Rounded Action)
  A --> D{Decision} --> F@{ shape: dbl-circ, label: "Final" }
  A --> B@{ shape: fork, label: "Fork/Join" }

What it shows: Typical UML‑like elements using Mermaid shapes.

---

14) Two worked examples

1) Order flow

flowchart LR
  subgraph Fulfillment
    direction TB
    Check{In stock?}
    Ship[Ship order]
    Wait[Wait for stock]
  end

  Start([Start]) --> Check
  Check -->|Yes| Ship --> Done(((Done)))
  Check -->|No| Wait --> Check

What it shows: A decision with Yes/No labels, a loop back, and a subgraph grouping fulfillment tasks. (Subgraph may inherit parent direction if nodes link outside.) (Mermaid)

2) Login flow

flowchart TD
  Ask[/Enter username & password/] --> Verify[(Users DB)]
  Verify --> Valid{Valid?}
  Valid -->|Yes| Go[Open dashboard]
  Valid -->|No| Show[\Show error/]
  Go --> End(((End)))

What it shows: I/O nodes, a database (cylinder), a decision, and an end node.

---

15) Final checklist

• ☒ Syntax validated: no lowercase end nodes; no accidental o/x edge heads. (Mermaid)
• ☒ Every section has at least one code example and a What it shows line.
• ☒ UML meanings are clearly stated or marked “no standard UML equivalent.”
• ☒ Direction is layout only; flowchart and graph are aliases. (Mermaid)
• ☒ Edge features shown: labels, multi‑directional arrows, dotted/thick, invisible, chain &, and extra dashes for spacing. (Mermaid)
• ☒ Styling: node style, classDef/class, linkStyle, and curve styles; note edge‑level curves with Edge IDs (v11.10+). (Mermaid)
• ☒ Advanced shapes: expanded shapes (v11.3+) and Font Awesome icon packs (v11.7+) included. (Mermaid)

---

Source of truth: Mermaid Flowchart documentation (v11.12.0 page at time of writing). See sections on directions, shapes (classic and expanded), edges, subgraphs (including the direction limitation), styling/classes (including curves and edge IDs), click interaction, and icons/images. (Mermaid)