Mermaid Flowchart Diagram: Syntax, Examples & Templates

A flowchart maps a process step by step with boxes, arrows, and decision diamonds so anyone can follow the logic at a glance.

Open flowchart diagram in the editor

A flowchart is the diagram people reach for first, and for good reason: boxes and arrows map directly onto how most of us think about process. Before writing any code, decide two things — what each step is, and which steps involve a choice. Everything else in the syntax exists to serve those two ideas.

Basic syntax

Every flowchart opens with a declaration line that also sets the reading direction: flowchart TD flows top-down, while flowchart LR flows left-to-right. Each following line either defines a node or connects two of them. A[New bug report] creates a node with the internal id A and the visible label New bug report. The arrow --> draws a directed edge, and you can chain several connections on one line or spread them out — one edge per line is easier to edit later. Labels on edges use the -- text --> form, which is how you annotate the branches leaving a decision.

Node shapes and edges

Shape carries meaning, so pick deliberately. Square brackets [Step] render a rectangle, the default for actions. Curly braces {Reproducible?} render a diamond — reserve these for actual decisions, not for ordinary steps, or the diagram loses its signal. Double parentheses ((Done)) draw a circle, which works well for start and end markers, and [(Issue tracker)] draws a cylinder, the conventional shape for storage such as a database or a queue. Edges can also be plain lines when direction does not matter, but arrows are clearer in almost every case. The two examples above show the same vocabulary in both directions: the triage flow reads top-down like a runbook, while the review flow reads left-to-right like a pipeline.

Common gotchas

Two parsing rules cause nearly all flowchart errors. First, if a label contains parentheses, brackets, commas, or colons, wrap the entire label in double quotes: C["Deploy (staging)"]. An unquoted parenthesis makes the parser think the node definition has ended, and the error message rarely points at the real line. Second, node ids must be unique — writing B[...] twice does not create two nodes; it silently merges them into one with two labels. Also remember that the direction keyword lives on the first line only; you cannot change direction mid-diagram.

Tips for mobile editing

On a phone, vertical space is cheap and horizontal space is not, so prefer TD for anything with more than four or five steps. Keep ids to one or two characters and put each edge on its own line — tapping to place a cursor in the middle of a long chained line is fiddly. Short labels wrap more predictably than long ones, so move detail into edge labels or trim it entirely. When you finish a change, check the rendered result before the next edit; catching a broken bracket immediately beats scrolling through thirty lines to find it. The cheatsheet condenses every shape and arrow type into one page worth keeping open beside the editor.

Flowcharts pair naturally with other diagram types: use a sequence diagram when the order of messages between systems matters more than the branches, or a state diagram when you are really describing the modes a single thing moves through rather than a process a person follows.

Flowchart Diagram templates

Every template opens in the editor with the code pre-filled — edit it on your phone or desktop.

flowchart User Onboarding Flowchart Map a new user's journey from landing page to activation, with email verification, fallback loops, and a clear success endpoint.

flowchart Order Fulfillment Flowchart Trace an e-commerce order from checkout to delivery, covering payment failure, backorders, carrier handoff, and the support escalation path.

flowchart Decision Tree Flowchart Route incoming requests through a chain of yes-or-no questions until each one lands in the right queue, with every branch converging on one endpoint.

flowchart Incident Response Flowchart A page-ready on-call runbook that routes alerts by severity, enforces acknowledgment, tracks root cause investigation, and ends in a postmortem.

flowchart CI/CD Pipeline Flowchart Document a delivery pipeline from push to production, with test gates, staging smoke checks, a manual approval step, and a clear failure path.

flowchart Customer Support Triage Flowchart Sort incoming tickets by account value and churn risk, assign the right agent tier, enforce response targets, and escalate anything left unresolved.

flowchart Approval Workflow Flowchart Model a two-level signoff process where a manager reviews first and finance steps in only when the request amount crosses a set threshold.

flowchart Swimlane Process Flowchart Show an order-to-delivery process across four team lanes, making every handoff between customer, sales, warehouse, and shipping visible at a glance.

flowchart Fault Handling Flowchart Chart how a request survives upstream failure, with labeled timeout and error branches, a retry budget, cached fallback, and a degraded mode log.

flowchart Data Pipeline Flowchart Map a nightly extract, validate, transform, and load job, including a quarantine branch for bad rows and a dashboard refresh at the end.