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 aclicktooltip 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%% textor 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 asdb,decisionorsubroutine. 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 unlesslabelTypeistextorstring.icon: "prefix:name"draws an icon from a pack the embedding page registers, 48px square orhpixels, in aformofsquare,roundedorcircle, with the label below it or above withpos: t. The Playground registers no packs, so an icon node reports an error there.img: "data:image/…"draws an image at its natural size orwbyh(constraint: onkeeps its proportions), with the label below or, withpos: 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 --> Band only laterB[End], the label isB. 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| BorA -- 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-fillpaints, 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 ~~~ Bkeeps A and B apart as an edge would without drawing a line. Each extra~pushes B one rank further away. It counts inlinkStylenumbering, andlinkStyle N stroke-width:4pxmakes it visible; a label on it is drawn. - Chaining:
A --> B --> Cmakes two edges. - Many to many:
A & B --> C & Dmakes four edges: A-C, A-D, B-C, B-D. The&needs a space on each side:A&Bis one node namedA&B, andA &BorA[x]&Bis an error.A & Bwith no arrow declares both nodes. - Self-loops:
A --> A. - Semicolons:
A --> B; B --> Cputs 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@--> Bgives the edge the ide1, which the timeline andclassuse in place ofA-B. It can be written with either label form and on each link of a chain. It cannot name an edge of anA & B --> Cgroup, repeat a node’s id or another edge’s (including a derivedA-B), begin with a keyword, or be a subgraph’s name.e1@{ … }on a line below the edge is that edge’s data.animate: trueoranimation: fastmarches the line’s dashes on a 20-second cycle,animation: slowon a 50-second one; the march runs beside the timeline’s own effects and stops when the reader prefers reduced motion.curve: steppicks the curve aslinkStyle … interpolatedoes, the later of the two winning. Any other key is ignored with a warning; an animation other thanfastorslow, or a curve Siren does not draw, is an error. Written above the edge, the block declares a nodee1instead and is an error.class e1 nameapplies a style class to the edge: its declarations reach the line andcolorthe label, beneath anylinkStylethat names the edge.style e1 …andclick e1 …are errors; style an edge withlinkStyle.
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), andsubgraph 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, andsubgraph "t" [Ingest]is the idtwith 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 isendare errors, and so is an@{ … }block on a subgraph’s id. - Close it with
end. Subgraphs can nest. - Inside,
directioncan 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 nodirectionis 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 --> FwhereFis insideB, both insideAwithdirection 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, thenXreads 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:#1e3a8afills 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; uselinkStyle.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 nameorA:::name: applies a style class to nodes or subgraphs, andclass e1 nameto 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,dis an error. Applying a class noclassDefdefines reports a warning and the target is drawn unstyled.classDef default prop:value,...: styles every node, beneath any other class orstyleon 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;defaultapplies 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 isrounded: 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 arebasis(a smooth curve, which draws no jump),linear,step,stepBeforeandstepAfter. Names are case-sensitive, and a numbered statement’s curve beatsdefault’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 drawnroundedwith a warning.colorapplies to the text; the other properties apply to the shape (an edge’sstrokeaffects both the line and the arrowhead).stylebeats a class on the same target, whichever is written first, as in Mermaid. Between twostylelines, 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
strokeandstroke-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 asrgb(…)orvar(--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 wasrgb(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 asjavascript:) are rejected, and that interaction is dropped. - A callback fires the
onClicksupplied by the embedding page. Clicking in the Playground does nothing. - The tooltip shows when the pointer is over the node.
clickreaches 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 --> CareA-BandB-C. - The two edges of
A & B --> CareA-CandB-C. - Repeats are counted across every edge between a pair, named or not:
A e1@--> Bfollowed byA --> Baree1andA-B#2. - An edge to a subgraph uses the name written in the source: the id of
ingest --> storeisingest-store. The subgraph itself, though, can be named only assubgraph:N, not by its name. - When a node and an edge share an id (a node
A-BbesideA --> 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 |