Flowchart

flowchart LR
  A([Start]) --> B{OK?}
  B -->|yes| C[(Database)]
  B -- no --> D[/Input/]:::warn
  C & D ==> E(((End)))
  subgraph grp [Retry]
    direction TB
    F --> G
  end
  E -.-> grp
  classDef warn fill:#fde68a,color:#92400e

timeline:
  enter C slide-right, enter B-C fade
  enter D slide-bottom, enter B-D fade, highlight D glow
  enter subgraph:1 fade, enter E-grp fade

Header and direction

flowchart and graph mean the same thing, and must be followed by a direction:

Direction Meaning
TB, TD Top to bottom
BT Bottom to top
LR Left to right
RL Right to left

The direction must be uppercase, and the header cannot end with a semicolon. Only inside a subgraph can direction set a different direction: a direction LR written outside one does nothing, the diagram keeps the header’s direction, and a warning says so.

Comments

  • A line whose first non-blank characters are %% is a comment. A %% later on a line is not: inside a node label, an edge label, a subgraph title or a click tooltip it is kept as text (A[50 %% done] draws “50 %% done”), and after a complete statement (A --> B %% note) it reports an error asking to move the comment to a line of its own.
  • A line that is nothing but %% is an error too; write %% text or leave the line blank.
  • Inside a timeline: block, %% starts a comment anywhere on the line.

Nodes

A node id is made of letters, digits, _, . and - (for example step1, api.v2, a-b); a - cannot be followed by >, - or ., because that begins an arrow. A bare id is drawn as a rectangle labelled with the id.

An id cannot be a keyword such as end, style, class, subgraph or graph, or begin with one followed by punctuation (end-x, style.x, A --> end are errors, and the message suggests a name such as endX). An id that merely contains the word (endX, end_x, A-end) is fine.

Syntax Shape
A[text] Rectangle
A(text) Rounded rectangle
A([text]) Stadium
A[[text]] Subroutine
A[(text)] Cylinder (database)
A((text)) Circle
A(((text))) Double circle
A>text] Flag
A{text} Rhombus (decision)
A{{text}} Hexagon
A[/text/] Parallelogram
A[\text\] Reverse parallelogram
A[/text\] Trapezoid
A[\text/] Inverted trapezoid

Shape data block

flowchart LR
  A@{ shape: cloud, label: "Internet" } --> B@{ shape: doc, label: "Report" }
  C[Queue]@{ shape: h-cyl }
  D@{
    shape: person
    label: "Reader"
  }
  • A@{ … } gives a node its shape and text as YAML: on one line a flow mapping, across lines block YAML (a line break inside a quoted string is drawn as <br/>). It can stand on a node’s own line, at either end of an edge, after brackets or a :::name (A[x]:::c@{ shape: circle }), and on a node written earlier, which keeps its text. No space before the @, nothing after the }, and one block per node; a block on a subgraph’s id is an error.
  • shape: names the shape. The fourteen bracket shapes are available by name — rect, rounded, stadium, fr-rect, cyl, circle, dbl-circ, odd, diam, hex, lean-r, lean-l, trap-b, trap-t — and by their aliases, such as db, decision or subroutine. The table below lists the rest. A name that is no shape (foo, Rect) is an error, and a key Siren does not know is ignored with a warning.
  • label: gives the text, read as a Markdown string unless labelType is text or string.
  • icon: "prefix:name" draws an icon from a pack the embedding page registers, 48px square or h pixels, in a form of square, rounded or circle, with the label below it or above with pos: t. The Playground registers no packs, so an icon node reports an error there.
  • img: "data:image/…" draws an image at its natural size or w by h (constraint: on keeps its proportions), with the label below or, with pos: t, above. Only a data URL is drawn; an image at any other URL is an error asking to embed it. PNG, GIF, JPEG, WebP and SVG up to 4 MB.
Shape Names
Notched rectangle (card) notch-rect, card, notched-rectangle
Notched pentagon (loop limit) notch-pent, loop-limit, notched-pentagon
Sloped rectangle (manual input) sl-rect, manual-input, sloped-rectangle
Triangle tri, extract, triangle
Flipped triangle (manual file) flip-tri, manual-file, flipped-triangle
Folder folder, directory
Lined rectangle lin-rect, lined-rectangle, lined-process, lin-proc, shaded-process
Divided rectangle div-rect, div-proc, divided-rectangle, divided-process
Window pane (internal storage) win-pane, internal-storage, window-pane
Stacked rectangles st-rect, procs, processes, stacked-rectangle
Tagged rectangle tag-rect, tagged-rectangle, tag-proc, tagged-process
Text with no frame text
Data store datastore, data-store
Half-rounded rectangle (delay) delay, half-rounded-rectangle
Curved trapezoid (display) curv-trap, curved-trapezoid, display
Horizontal cylinder h-cyl, das, horizontal-cylinder
Lined cylinder (disk) lin-cyl, disk, lined-cylinder
Bow-tie rectangle (stored data) bow-rect, stored-data, bow-tie-rectangle
Document doc, document
Lined document lin-doc, lined-document
Tagged document tag-doc, tagged-document
Stacked documents docs, documents, st-doc, stacked-document
Paper tape flag, paper-tape
Curly brace, left or right, or both brace (comment, brace-l), brace-r, braces
Bucket bucket
Person person
Console (a window with a >_ prompt) console
Browser (a window with a bar and an address field) browser
Cloud cloud
Bang bang
Fork bar fork, join
Hourglass hourglass, collate
Lightning bolt bolt, com-link, lightning-bolt
Small circle sm-circ, start, small-circle
Framed circle fr-circ, stop, framed-circle
Filled circle f-circ, junction, filled-circle
Crossed circle cross-circ, summary, crossed-circle

The last seven are drawn at a fixed size with no text: a label written for one, in brackets or as label:, is an error. A style or class on a small circle is an error too, since it would change nothing.

Labels

  • Labels can contain non-ASCII text, such as Chinese.
  • To put brackets, |, ;, & or an arrow in a label, wrap it in double quotes: A["a (b) | c"]. The quotes themselves are not drawn. A %% inside a label is text.
  • An unquoted label cannot contain a bracket that is not the shape’s own: A[a]b], A[a}b], A{a]b} and an unpaired ( or ) (A[a)b]) each report an error asking to quote the label. A balanced pair of parentheses is drawn as written (A[f(x)]).
  • Markdown strings: A["`**bold** and *italic*`"]. Inside the backticks you can break lines directly, and the line breaks are drawn as written. This syntax works only in node labels.
  • <br> breaks a row wherever you put it: A["first row<br>second row"]. A row that is still too long is then wrapped on its own.
  • Long labels wrap by themselves, as in Mermaid: once the text is wider than 175px, it breaks at spaces, or between any two CJK characters, onto more rows, and the node grows taller rather than wider. Closing punctuation such as , or ) never begins a row, and a single word too long for the width is left whole. A subgraph’s title never wraps.
flowchart LR
  A["first row<br>second row"] --> B[A label long enough to wrap onto a second row by itself]
  • When the same node is declared twice with different labels, the first label is kept and a warning is reported. A bare id counts as a declaration too: if you write A --> B and only later B[End], the label is B. Give a node its label the first time you mention it.

Edges

An arrow is made of three parts: the line, the ends, and the length.

Line Syntax
Solid -->, ---
Thick ==>, ===
Dotted -.->, -.-
End Syntax
Arrow -->, both ways <-->
Circle --o, both ways o--o
Cross --x, both ways x--x
None ---

Ends combine freely with all three lines, for example ==o, <-.->. A two-way edge must have the same end on both sides; o--x and <-.- are rejected (Mermaid silently draws them wrong; Siren reports an error instead). An arrow ends on the node’s outline: into a rhombus, a circle or a slanted shape it meets the side or the arc itself rather than the box around it.

  • Length: add characters to make the line longer, for example ---->, -...->, ====>.
  • Labels: A -->|text| B or A -- text --> B (thick == text ==>, dotted -. text .->). The two forms cannot be used on the same edge, and a label cannot be empty. An edge label is drawn on the line, on a background the theme’s --siren-edge-label-fill paints, and wraps once it is wider than 150px, by the same rules as a node’s label; <br> breaks a row here too. In the |text| form, an unquoted bracket (A -->|a{b| B), a first word holding an @, or a quote anywhere but at the start is an error: quote the whole label (A -->|"a{b"| B). The other form draws such text as written (A -- a{b --> B).
  • Invisible edges: A ~~~ B keeps A and B apart as an edge would without drawing a line. Each extra ~ pushes B one rank further away. It counts in linkStyle numbering, and linkStyle N stroke-width:4px makes it visible; a label on it is drawn.
  • Chaining: A --> B --> C makes two edges.
  • Many to many: A & B --> C & D makes four edges: A-C, A-D, B-C, B-D. The & needs a space on each side: A&B is one node named A&B, and A &B or A[x]&B is an error. A & B with no arrow declares both nodes.
  • Self-loops: A --> A.
  • Semicolons: A --> B; B --> C puts several statements on one line.

Edge ids and edge data

flowchart LR
  A e1@--> B e2@-->|retry| C
  e1@{ animate: true }
  e2@{ animation: slow, curve: step }
  classDef hot stroke:#dc2626
  class e2 hot
  • A e1@--> B gives the edge the id e1, which the timeline and class use in place of A-B. It can be written with either label form and on each link of a chain. It cannot name an edge of an A & B --> C group, repeat a node’s id or another edge’s (including a derived A-B), begin with a keyword, or be a subgraph’s name.
  • e1@{ … } on a line below the edge is that edge’s data. animate: true or animation: fast marches the line’s dashes on a 20-second cycle, animation: slow on a 50-second one; the march runs beside the timeline’s own effects and stops when the reader prefers reduced motion. curve: step picks the curve as linkStyle … interpolate does, the later of the two winning. Any other key is ignored with a warning; an animation other than fast or slow, or a curve Siren does not draw, is an error. Written above the edge, the block declares a node e1 instead and is an error.
  • class e1 name applies a style class to the edge: its declarations reach the line and color the label, beneath any linkStyle that names the edge. style e1 … and click e1 … are errors; style an edge with linkStyle.

Subgraph

flowchart TB
  subgraph ingest [Ingest]
    direction LR
    Fetch --> Parse
  end
  subgraph store [Store]
    Save
  end
  ingest --> store
  • There are several ways to open one: subgraph ingest (id and title are both ingest), subgraph ingest [Ingest pipeline] (an id and a title), subgraph "Ingest pipeline" (a title only; nothing else can refer to it by id), and subgraph Ingest pipeline, an unquoted title of several words, which is also a title only. A quoted title of one word (subgraph "t") is its id as well, and subgraph "t" [Ingest] is the id t with a title.
  • An unquoted title cannot hold ,, (, [, {, |, <, =, ~, @, -- or :::; quote it instead. Words after a bracketed title (subgraph s1 [t] zz) and a title whose last word is end are errors, and so is an @{ … } block on a subgraph’s id.
  • Close it with end. Subgraphs can nest.
  • Inside, direction can set a different direction that affects only that level; text after the value (direction LR zz) is ignored with a warning. The direction is given up as soon as an edge whose two ends have different parents passes through the subgraph: one end inside it (at any depth) and one outside, or two of its own members at different nesting depths. Such an edge voids every subgraph from each end up to and including the two ends’ nearest common one, and each is then laid out in the direction of the nearest enclosing subgraph that keeps its own, or else the diagram’s, as in Mermaid 12. A subgraph that names no direction is laid out the same way, in its enclosing subgraph’s direction. An edge between two subgraphs or nodes side by side (ingest --> store) counts for neither; an edge from a member to its own subgraph does.
  • One picture cannot be laid out, and reports an error naming the pieces: inside a subgraph that keeps its own direction, an edge between a nested subgraph and one of its own members (B --> F where F is inside B, both inside A with direction LR). Remove the direction from the outer subgraph, or connect the nested one to something outside it.
  • Sibling subgraphs are placed last-closed first, and every subgraph before the nodes outside them, as in Mermaid: subgraph SA … end, subgraph SB … end, then X reads SB, SA, X from left to right.
  • Edges can connect to a subgraph’s id directly (ingest --> store), even when the subgraph is written below the edge.
  • A node belongs only to the first subgraph that mentions it.

Styles

flowchart LR
  A:::hot --> B --> C
  style B fill:#e0f2fe,stroke:#0284c7
  classDef hot fill:#fee2e2,stroke:#dc2626,color:#991b1b
  class C hot
  linkStyle 0 stroke:#dc2626
  linkStyle 1 interpolate step
  linkStyle default stroke:#94a3b8
  • style node prop:value,prop:value: applies to one node, or to one subgraph by its id (style ingest fill:#f0f9ff,color:#1e3a8a fills the frame and colours the title). When a name belongs to both a node and a subgraph, the subgraph is styled. An edge id is not accepted here; use linkStyle.
  • classDef name prop:value,...: defines a style class. The name may hold letters, digits and _, letters of any script, and -, ., # or + between words; it cannot begin with a digit. classDef a,b ... defines both classes. It can come before or after the statements that apply it.
  • class A,B name or A:::name: applies a style class to nodes or subgraphs, and class e1 name to an edge with an id. ::: can also follow a labelled node or an edge endpoint (A[x]:::hot --> B:::cold). One class at a time: A:::c,d is an error. Applying a class no classDef defines reports a warning and the target is drawn unstyled.
  • classDef default prop:value,...: styles every node, beneath any other class or style on it. It does not reach subgraphs.
  • linkStyle 0 ..., linkStyle 0,2 ..., linkStyle default ...: styles edges. Numbers count from 0 in the order edges are declared, invisible ~~~ edges included; default applies to every edge, but numbered ones take precedence property by property.
  • linkStyle 1 interpolate step, linkStyle default interpolate linear, or with declarations on the same line, linkStyle 1 interpolate step stroke:#f00: picks the curve an edge is drawn with, as in Mermaid. By default an edge is rounded: a route of horizontal and vertical runs with rounded corners, the way Mermaid 12 draws it, and where two edges cross, one jumps the other with a small arc. The others are basis (a smooth curve, which draws no jump), linear, step, stepBefore and stepAfter. Names are case-sensitive, and a numbered statement’s curve beats default’s. The seven curves Mermaid draws and Siren does not yet (cardinal, bumpX, bumpY, catmullRom, monotoneX, monotoneY, natural) report an error and the edge keeps its curve; a name Mermaid does not know either is drawn rounded with a warning.
  • color applies to the text; the other properties apply to the shape (an edge’s stroke affects both the line and the arrowhead).
  • style beats a class on the same target, whichever is written first, as in Mermaid. Between two style lines, or two classes, on one target, the property written later wins.
  • While the timeline highlights a target, the highlight’s colour and width replace the author’s stroke and stroke-width, and come back when the highlight ends.
  • Referring to a node that does not exist is skipped silently, as in Mermaid.
  • Values are written as in Mermaid: a colour as a hex code or a name (fill:#ff0000, fill:red), a font with single quotes (font-family:'Noto Sans'). A CSS function such as rgb(…) or var(--x), a bracket, |, @, {, }, =, ~, an arrow or two dashes in a row, a double quote, ; or a backslash is an error, with the hex to write when the value was rgb(r,g,b). A space inside a value is fine (stroke-dasharray:5 5).

Interaction

flowchart LR
  Docs --> API
  click Docs href "https://example.com/docs" "Documentation" _blank
  click API call openPanel("api")
Syntax Effect
click A href "url" or click A "url" Link
click A href "url" "tooltip" _blank or click A "url" "tooltip" _blank Shows the tooltip on hover and opens in a new tab; _self, _top and _parent also work
click A call fn(), click A call fn("arg") Calls a callback
click A fn Shorthand for a callback
  • Only http:, https:, mailto: and relative URLs are allowed. Other protocols (such as javascript:) are rejected, and that interaction is dropped.
  • A callback fires the onClick supplied by the embedding page. Clicking in the Playground does nothing.
  • The tooltip shows when the pointer is over the node.
  • click reaches only nodes: an edge id is an error.

Accessibility

accTitle: title and accDescr: description become the SVG’s <title> and <desc>, and a description may span several lines as accDescr { ... }. A space before the colon is fine. If written more than once, the last one wins.

Timeline targets

Element id Example
Node The node id B
Edge from-to, with #2, #3 for repeats A-B, A-B#2
Edge with an id The id written before the arrow e1
subgraph subgraph:N, numbered in the order they open, nested ones included subgraph:1
  • The two edges of A --> B --> C are A-B and B-C.
  • The two edges of A & B --> C are A-C and B-C.
  • Repeats are counted across every edge between a pair, named or not: A e1@--> B followed by A --> B are e1 and A-B#2.
  • An edge to a subgraph uses the name written in the source: the id of ingest --> store is ingest-store. The subgraph itself, though, can be named only as subgraph:N, not by its name.
  • When a node and an edge share an id (a node A-B beside A --> B), naming it in the timeline is an error; give the edge an id of its own or rename the node.

Not yet supported

Syntax Current behavior
Non-ASCII node ids (café --> B) Error. Put non-ASCII text in the label: n1[café]
A@{ icon: "fa:user" } in the Playground Error: no icon pack is registered there
A@{ img: "https://…" } Error; only a data: URL is drawn
A ~~ B, A ~~~> B Error; an invisible edge is ~~~ with no ends
#quot;, fa: icons in a label Drawn as plain text
Markdown in edge labels and subgraph titles Drawn as plain text