Skip to content
MermaidViewer

Process diagram

Mermaid flowchart syntax

Mermaid flowchart syntax for nodes, arrows, subgraphs and direction, with examples you can edit. PNG export is on every plan.

By MermaidViewer editorsPublished Updated

Basic flowchart example

Basic flowchart example diagram
mermaid
flowchart TD
    A([User opens app]) --> B{Signed in?}
    B -- Yes --> C[Load dashboard]
    B -- No --> D[Show login form]
    D --> E[/Enter credentials/]
    E --> F{Valid?}
    F -- Yes --> C
    F -- No --> G[Show error]
    G --> D
    C --> H[(Fetch data from DB)]
Open in the live editor

A Mermaid flowchart turns a few lines of plain text into a clean process diagram. You declare nodes, connect them with arrows, and Mermaid lays everything out automatically, so you never have to drag boxes around or fix crooked connectors again.

Flowcharts are the most popular Mermaid diagram type because they work everywhere: README files on GitHub and GitLab, Notion and Obsidian notes, Confluence pages, technical design docs and pull-request descriptions. Because the source is text, a flowchart lives next to your code, diffs cleanly in version control and stays easy to update.

When to use a flowchart

  • Documenting business processes and approval workflows
  • Explaining algorithms and decision logic in code reviews
  • Onboarding guides and support troubleshooting trees
  • CI/CD pipelines and deployment runbooks

Flowchart syntax reference

SyntaxWhat it does
flowchart TDStart a flowchart. Direction: TD/TB (top-down), BT, LR (left-right) or RL.
A[Text]Rectangle node with id A and a label.
A(Text) / A([Text])Rounded rectangle / stadium (pill) shape.
A{Text}Diamond — use for decisions.
A[(Text)] / A((Text))Database cylinder / circle.
A[/Text/]Parallelogram — input or output.
A --> BArrow from A to B.
A -- label --> B or A -->|label| BArrow with a text label.
A -.-> B / A ==> BDotted arrow / thick arrow.
subgraph Title ... endGroup nodes into a labelled box.
classDef hot fill:#fee,stroke:#f00Define a reusable style; apply with A:::hot.
%% commentComment line, ignored by the renderer.

Flowchart examples

Left-to-right pipeline with subgraphs

Subgraphs group related steps. Here a CI/CD pipeline is split into build and deploy stages.

Left-to-right pipeline with subgraphs diagram
mermaid
flowchart LR
    subgraph Build
      A[Commit] --> B[Install deps] --> C[Run tests]
    end
    subgraph Deploy
      D[Build image] --> E[Push to registry] --> F[Roll out]
    end
    C -->|tests pass| D
    C -.->|tests fail| X[Notify team]
Open in the live editor

Styled decision tree

Use classDef to color nodes by meaning so readers scan the result faster.

Styled decision tree diagram
mermaid
flowchart TD
    Q{Bug reproducible?} -->|Yes| W[Write failing test]
    Q -->|No| I[Ask for more info]
    W --> F[Fix and open PR]
    F --> R{Review approved?}
    R -->|Yes| M[Merge]:::ok
    R -->|No| F
    classDef ok fill:#d1fae5,stroke:#059669,color:#064e3b
Open in the live editor

Once the syntax table is familiar, mermaid flowchart syntax still decides whether a refund policy is readable or a knot of arrows. Direction, subgraphs, and a couple of styles do more for a reader than extra shapes. This section walks through one approval flow, the layout choices inside it, and the mistakes that make Mermaid draw the wrong picture.

How direction and grouping change the reading order

A top-down flowchart matches a decision tree. The question sits above the answers, and the eye drops through yes and no. A left-to-right flowchart matches a pipeline, where each stage hands work to the next. Pick the direction from the story, then keep it. Mixing directions inside one diagram is allowed on a subgraph, and it's also the fastest way to make a small process look like a maze.

Node ids are for you. Labels are for the reader. req, gate, and pay stay stable when you rewrite the label from "Manager review" to "Finance review". If the id and the label are the same long sentence, every rename touches the arrows too.

Subgraphs are the other layout tool that matters. They don't change the logic. They tell the reader which steps belong to the customer, which belong to finance, and which are the unhappy path. A subgraph title is a heading. If you can't name the box in two words, the nodes inside it are probably two processes.

classDef is worth using once the diagram is correct. Color a decision, a failure, and a terminal success, and stop. Five colors turn the chart into a legend the reader has to decode before they can follow the arrows.

Worked example

A shop refunds orders under fifty dollars automatically. Larger refunds wait for a manager, and a rejected request goes back to the customer with a reason. The diagram below is the policy a support lead would paste into a runbook.

Mermaid diagram
mermaid
flowchart TD
    subgraph Intake
      req[Refund request] --> gate{Over 50?}
    end
    gate -->|No| auto[Auto approve]
    gate -->|Yes| mgr[Manager review]
    mgr -->|Approved| pay[Send refund]
    mgr -->|Rejected| why[Email the reason]
    auto --> pay
    classDef ok fill:#d1fae5,stroke:#059669
    classDef no fill:#fee2e2,stroke:#b91c1c
    pay:::ok
    why:::no
Open in the live editor

flowchart TD stacks the decision under the request. The subgraph Intake holds only the request and the amount check, so the money decision is visually separate from the two outcomes. The labeled arrows |No| and |Yes| are the policy. Without those labels a diamond is just a fork. auto and the approved branch both land on pay, which is the point of the diagram: two paths, one payout. The red class sits only on the rejection email. A reader scanning for the unhappy path finds it without reading every box.

If this grew a fraud check, add it inside Intake or as a second subgraph. Don't drop ten more nodes into the same column and hope the arrows sort themselves out.

When this is the wrong diagram

Switch to a sequence diagram when the question is who calls whom, and in what order. A refund that's really "app calls payments, payments calls the bank, the bank answers" is a conversation, and a flowchart flattens that into boxes. Switch to a state diagram when the same order sits in Draft, Review, and Paid, and the arrows are events that move it. The flowchart above is a policy. It's a poor picture of an order's lifecycle.

Common mistakes

  1. A node id with a space, such as Refund request --> pay, is read as two tokens and the arrow never attaches. Put the words in the label: req[Refund request].
  2. The lowercase word end as a node id closes a subgraph. Name the last step done or quote the label.
  3. Parentheses inside an unquoted label, as in A[Call api(v2)], often break the shape parser. Wrap the label in quotes: A["Call api(v2)"].
  4. A decision diamond with two outgoing arrows and no labels forces the reader to guess which branch is yes. Use -->|Yes| and -->|No| on both.

Where to go next

Paste a rough policy into the AI flowchart generator when you want a first draft, then fix ids and labels by hand. The editor previews each change, and the cheat sheet keeps the arrow and shape forms on one page. A finished login example lives in the user login flowchart template if you want a second process to compare with this refund.

The syntax above is the reference. Longer writing lives on the blog: flow charts as symbols and judgment, what flowcharts mean, what a flowchart is used for, a five-minute build, data flow diagrams from the same shapes, a text alternative to Visio, and online flowchart tools.

Tips and best practices

  • Pick the direction that matches reading order: LR for pipelines and timelines, TD for hierarchies and decision trees.
  • Keep node ids short (A, B, login) and put the human text in the label — ids must be unique and cannot contain spaces.
  • Wrap labels containing special characters such as parentheses or quotes in double quotes: A["Call api(v2)"].
  • Avoid the bare word end in lowercase as a node label — it closes subgraphs. Use End or "end" instead.
  • If the layout gets tangled, split the diagram into subgraphs or several smaller diagrams.

Generate a flowchart with AI

Not sure where to start? Describe what you need and the AI flowchart generator writes the Mermaid code for you. Try prompts like:

  • “User signup flow with email verification and error handling”
  • “Order fulfilment process from checkout to delivery”
  • “Incident response runbook for a production outage”

Flowchart templates

Flowchart FAQ

What is the difference between graph and flowchart in Mermaid?

Both keywords render the same kind of diagram. flowchart is the newer keyword and supports extra features such as more node shapes and better subgraph handling, so it is recommended for new diagrams.

How do I change the direction of a Mermaid flowchart?

Put the direction after the keyword: flowchart TD (top-down), flowchart LR (left to right), flowchart BT (bottom-up) or flowchart RL (right to left). Subgraphs can also set their own direction with a direction LR line.

How do I add a link or click action to a node?

Use click A "https://example.com" to make node A a hyperlink. In strict security mode (used for shared diagrams on MermaidViewer) JavaScript callbacks are disabled, but plain links still work.

Can I export a Mermaid flowchart as an image?

Yes. Every plan can download a PNG. Free is 1× with a small watermark, Starter goes to 4× with no watermark, and Pro goes to 8×. JPG, SVG and PDF downloads are on Pro.