Mermaid syntax reference

This article is the Help Center summary of every Mermaid diagram type. For each one you'll find what it's for, the minimum working syntax, any version requirements, and a link to the full open-source reference.

For complete documentation on every feature, configuration option, and shape, see the open-source syntax reference.

How to use this article

• Use the table of contents (or Ctrl/Cmd+F) to jump to a diagram type.
• Each section gives you a minimum working example you can paste into the editor.
• Where a feature requires a specific Mermaid version, you'll see a version note like v11.13.0+. To check which Mermaid version your editor is running, type info on its own line in the code box and run it.

About Mermaid versions

Not every diagram type or feature is available in every Mermaid environment, and version coverage varies between them. To check the Mermaid version any environment is running, type info on its own line in the code box and run it.

Where each environment runs:

• mermaid.live — typically tracks the latest stable Mermaid release closely.
• mermaid.ai editor — runs a Mermaid version chosen for stability with our visual editor and other features. It does not always match mermaid.live. If a feature works in mermaid.live but not in the mermaid.ai editor, the most likely cause is a version difference. Use info to confirm.
• Plugins (Confluence, VS Code, Word, PowerPoint, JetBrains, etc.) — depend on each plugin's own release schedule. Update the plugin to get the latest Mermaid version.
• Self-hosted Mermaid library (your own site, GitLab, GitHub README, Notion code blocks, etc.) — whatever version is pinned in that environment.

If a diagram works on mermaid.live but not in your mermaid.ai editor, the diagram type or feature was added in a Mermaid version newer than your editor is running. 

Conventions used across most diagrams

These work the same way across multiple diagram types — explained once here so each diagram-type section below can stay focused.

Comments

Lines starting with %% are ignored by the parser. Comments must be on their own line.

%% This is a comment
flowchart TD
    A --> B

Themes and styling

Most diagram types support themes (default, neutral, forest, dark, base) via a frontmatter block at the top of your code:

---
config:
  theme: dark
---
flowchart TD
    A --> B

Many diagrams also support classDef for reusable styles applied with the :::className shorthand. See the theming docs for the full picture.

Special characters in labels

Wrap labels containing special characters (@, &, (, :, non-English text) in double quotes:

flowchart TD
    A["User & Account"] --> B["Settings (admin)"]

Frontmatter for titles and config

Most diagrams accept a frontmatter block (between two --- lines) for the diagram title and config:

---
title: My Diagram
config:
  theme: forest
---
flowchart LR
    A --> B

---

Flowchart

Flowcharts represent processes as boxes (nodes) connected by arrows (edges). The most flexible diagram type and the one you'll use most often.

Where you can use it: available as a template in the mermaid.ai editor, and renders in mermaid.live.

Minimum example:

flowchart TD
    A[Start] --> B{Decision?}
    B -->|Yes| C[Do thing]
    B -->|No| D[Skip]
    C --> E[End]
    D --> E

Direction: TD or TB (top-down, default), BT (bottom-up), LR (left-right), RL (right-left). graph works as a synonym for flowchart.

Node shapes (original syntax): A[Rectangle], A(Rounded), A([Stadium]), A((Circle)), A{Diamond}, A[(Cylinder)], A{{Hexagon}}, A[/Parallelogram/].

Edge types: --> arrow, --- line, -.-> dotted, ==> thick, A -- text --> B labeled.

Expanded shapes (v11.3.0+): 30 additional shapes (cloud, document, hourglass, lightning bolt, manual input, etc.) using A@{ shape: cloud } syntax.

Common pitfalls:

• Lowercase end as a node ID will break the diagram (it conflicts with the end keyword for subgraphs). Use End or END.
• Lowercase o or x as the first letter of a target node creates an unwanted edge style: A---oB creates a circle-ended edge, A---xB creates a cross. Capitalize or add a space.

Full reference: Flowchart syntax docs.

---

Class diagram

UML class diagrams. Shows classes, attributes, methods, and relationships (inheritance, association, composition, etc.).

Where you can use it: available as a template in the mermaid.ai editor, and renders in mermaid.live.

Minimum example:

classDiagram
    class Animal {
        +String name
        +int age
        +eat()
    }
    class Dog
    Animal <|-- Dog

Relationships: <|-- inheritance, *-- composition, o-- aggregation, --> association, ..> dependency, ..|> realization.

Visibility: + public, - private, # protected, ~ package.

Note: notes inside namespaces was added in v11.13.0.

Full reference: Class diagram syntax docs.

---

Sequence diagram

Shows interactions between participants (people, systems, services) over time. Best for API flows, authentication flows, and message passing.

Where you can use it: available as a template in the mermaid.ai editor, and renders in mermaid.live.

Minimum example:

sequenceDiagram
    participant U as User
    participant S as Server
    U->>S: Login request
    S-->>U: Auth token
    U->>S: Fetch data
    S-->>U: Response

Arrow types: -> line, ->> solid arrow, --> dashed line, -->> dashed arrow, -x cross (failed call).

Notes and groupings: Note over A,B: text, loop, alt/else, opt, par, critical.

Common pitfall: participant names with spaces or special characters need an alias: participant U as "End User".

Full reference: Sequence diagram syntax docs.

---

State diagram

Shows the states of a system and the transitions between them. Useful for finite state machines, lifecycles, and approval flows.

Where you can use it: available as a template in the mermaid.ai editor, and renders in mermaid.live.

Minimum example:

stateDiagram-v2
    [*] --> Idle
    Idle --> Running: start
    Running --> Idle: stop
    Running --> [*]: shutdown

Notes:

• [*] represents start (when on the left of -->) or end (when on the right).
• Use stateDiagram-v2 rather than the older stateDiagram — v2 is the supported version.
• Composite (nested) states use state CompositeName { ... }.

Full reference: State diagram syntax docs.

---

Mindmap

Hierarchical idea maps. Indentation defines the hierarchy.

Where you can use it: available as a template in the mermaid.ai editor, and renders in mermaid.live.

Minimum example:

mindmap
  root((Project))
    Frontend
      React
      CSS
    Backend
      API
      Database
    DevOps
      CI/CD

Node shapes: use the same bracket conventions as flowchart. id((text)) for circles, id[text] for rectangles, id))text(( for cloud shape.

Common pitfall: indentation must be consistent. Mixed tabs and spaces will produce unexpected hierarchy.

Full reference: Mindmap syntax docs.

---

Entity Relationship (ER) diagram

Models data — entities (tables), attributes (columns), and relationships between them. Standard for database schema visualization.

Where you can use it: available as a template in the mermaid.ai editor, and renders in mermaid.live.

Minimum example:

erDiagram
    CUSTOMER ||--o{ ORDER : places
    ORDER ||--|{ LINE-ITEM : contains
    CUSTOMER {
        string name
        string email
    }
    ORDER {
        int orderNumber
        date created
    }

Cardinality notation: || exactly one, o| zero or one, }o zero or many, }| one or many. Combine on either side of the relationship line.

Full reference: ER diagram syntax docs.

---

Requirement diagram

Models requirements and how they relate to system elements. Used for system engineering and traceability.

Where you can use it: available as a template in the mermaid.ai editor, and renders in mermaid.live.

Minimum example:

requirementDiagram

    requirement test_req {
        id: 1
        text: the system shall do A
        risk: high
        verifymethod: test
    }

    element test_entity {
        type: simulation
    }

    test_entity - satisfies -> test_req

Requirement types: requirement, functionalRequirement, interfaceRequirement, performanceRequirement, physicalRequirement, designConstraint.

Relationship types: contains, copies, derives, satisfies, verifies, refines, traces.

Full reference: Requirement diagram syntax docs.

---

Architecture diagram

Visualizes cloud and service architectures with built-in icons. Good for AWS, Azure, GCP, and Kubernetes-style topologies.

Where you can use it: available as a template in the mermaid.ai editor, and renders in mermaid.live. Uses the architecture-beta syntax — syntax may evolve in future versions.

Minimum example:

architecture-beta
    group api(cloud)[API]

    service db(database)[Database] in api
    service disk1(disk)[Storage] in api
    service server(server)[Server] in api

    db:L -- R:server
    disk1:T -- B:server

Built-in icon shapes: cloud, database, disk, server, internet. Custom icons require icon pack registration (v11.7.0+).

Edges: the L, R, T, B after the colon specify which side of the service the connection attaches to (left, right, top, bottom).

Full reference: Architecture diagram syntax docs.

---

Block diagram

General-purpose block-and-arrow diagrams with explicit grid layouts. Useful for system-level diagrams where flowchart layout doesn't give you enough control.

Where you can use it: available as a template in the mermaid.ai editor, and renders in mermaid.live. Uses the block-beta syntax — syntax may evolve in future versions.

Minimum example:

block-beta
    columns 3
    a["Source"] b["Process"] c["Sink"]
    a --> b
    b --> c

Layout control: columns N sets the grid width. Block widths can span multiple columns with blockId<[wide]>.

Full reference: Block diagram syntax docs.

---

C4 diagram

The C4 model for software architecture (Context, Container, Component, Code). Useful for system-level architecture documentation.

Where you can use it: available as a template in the mermaid.ai editor, and renders in mermaid.live.

Status: the open-source docs mark C4 as experimental and subject to change. Test thoroughly before relying on it for long-term documentation.

Minimum example (C4 Context):

C4Context
    title System Context for Online Banking

    Person(customer, "Customer", "A bank customer")
    System(banking, "Internet Banking", "Allows customers to view accounts and make payments")
    System_Ext(email, "Email System", "Sends transaction notifications")

    Rel(customer, banking, "Uses")
    Rel(banking, email, "Sends emails via")

Diagram variants: C4Context, C4Container, C4Component, C4Dynamic, C4Deployment.

Full reference: C4 diagram syntax docs.

---

Gantt chart

Project timelines with tasks, durations, dependencies, and milestones.

Where you can use it: available as a template in the mermaid.ai editor, and renders in mermaid.live.

Minimum example:

gantt
    title Project Plan
    dateFormat YYYY-MM-DD
    section Design
    Wireframes :a1, 2026-05-01, 7d
    Mockups    :after a1, 5d
    section Build
    Frontend   :2026-05-15, 14d
    Backend    :2026-05-15, 14d

Task syntax: Task name :id, start, duration or Task :after otherTaskId, duration.

States: done, active, crit (critical) prefix the task definition: Wireframes :crit, a1, 2026-05-01, 7d.

Common pitfall: dateFormat applies to dates in your input. axisFormat controls how dates display on the rendered axis. Set both if you want a different display format from your input format.

Full reference: Gantt syntax docs.

---

Git graph

Visualizes git branching and commit history. Useful for documenting branching strategies and release flows.

Where you can use it: available as a template in the mermaid.ai editor, and renders in mermaid.live.

Minimum example:

gitGraph
    commit
    commit
    branch develop
    checkout develop
    commit
    commit
    checkout main
    merge develop
    commit

Commands: commit, branch, checkout, merge, cherry-pick.

Full reference: GitGraph syntax docs.

---

Kanban board

A Kanban-style board with columns and cards. Useful for project status snapshots and workflow visualization.

Where you can use it: available as a template in the mermaid.ai editor, and renders in mermaid.live.

Minimum example:

kanban
    Todo
        [Add login screen]
        [Wire up the API]
    In progress
        [Refactor the data layer]
    Done
        [Set up CI/CD pipeline]

Card metadata: add metadata blocks under cards using @{...} syntax — see the docs for fields like assigned, ticket, priority.

Full reference: Kanban syntax docs.

---

Packet diagram

Network packet structure visualization. Bit-level diagrams of protocol headers and message formats.

Where you can use it: available as a template in the mermaid.ai editor, and renders in mermaid.live. Uses the packet-beta syntax — syntax may evolve in future versions.

Minimum example:

packet-beta
    0-15: "Source Port"
    16-31: "Destination Port"
    32-63: "Sequence Number"
    64-95: "Acknowledgment Number"
    96-99: "Data Offset"

Syntax: bit-range start-end: "label" for multi-bit fields, single bits use position: "label".

Full reference: Packet diagram syntax docs.

---

Pie chart

Simple proportional charts. Best when you have 2–8 categories that sum to a meaningful whole.

Where you can use it: available as a template in the mermaid.ai editor, and renders in mermaid.live.

Minimum example:

pie title Browser usage
    "Chrome" : 64
    "Safari" : 19
    "Edge" : 5
    "Firefox" : 3
    "Other" : 9

Show values: add showData on the line below pie to show numeric values in the legend.

Full reference: Pie chart syntax docs.

---

Quadrant chart

Two-axis charts dividing the plane into four labeled quadrants. Common for prioritization (urgent/important), competitive analysis, and risk matrices.

Where you can use it: available as a template in the mermaid.ai editor, and renders in mermaid.live.

Minimum example:

quadrantChart
    title Reach and engagement of campaigns
    x-axis Low Reach --> High Reach
    y-axis Low Engagement --> High Engagement
    quadrant-1 We should expand
    quadrant-2 Need to promote
    quadrant-3 Re-evaluate
    quadrant-4 May be improved
    Campaign A: [0.3, 0.6]
    Campaign B: [0.45, 0.23]
    Campaign C: [0.57, 0.69]
    Campaign D: [0.78, 0.34]

Point coordinates: values are between 0 and 1. [0, 0] is bottom-left, [1, 1] is top-right.

Full reference: Quadrant chart syntax docs.

---

Sankey diagram

Flow diagrams where the width of arrows is proportional to flow quantity. Common for energy flows, budget allocations, and user journey volumes.

Where you can use it: available as a template in the mermaid.ai editor, and renders in mermaid.live. Uses the sankey-beta syntax — syntax may evolve in future versions.

Minimum example:

sankey-beta
    Visits,Sign-ups,40
    Visits,Bounce,60
    Sign-ups,Trial,25
    Sign-ups,Drop-off,15
    Trial,Paid,10
    Trial,Churn,15

Format: CSV-style — source,target,value on each line. No header row.

Full reference: Sankey diagram syntax docs.

---

Timeline

Event timelines grouped by section or period. Good for company history, product roadmaps, and project retrospectives.

Where you can use it: available as a template in the mermaid.ai editor, and renders in mermaid.live.

Minimum example:

timeline
    title History of social media
    2002 : LinkedIn
    2004 : Facebook : Google
    2005 : YouTube
    2006 : Twitter

Multiple events per period: separate with colons on the same line.

Sections: use section Name to group events:

timeline
    section Founding
        2002 : Company founded
    section Growth
        2010 : First product launch
        2015 : Series A

Full reference: Timeline syntax docs.

---

User journey

Maps user steps through a process, with satisfaction scores per step. Used for UX research, customer experience mapping, and onboarding analysis.

Where you can use it: available as a template in the mermaid.ai editor, and renders in mermaid.live.

Minimum example:

journey
    title My working day
    section Go to work
      Make tea: 5: Me
      Go upstairs: 3: Me
      Do work: 1: Me, Cat
    section Go home
      Go downstairs: 5: Me
      Sit down: 5: Me

Step format: Task name: score (1–5): Actor1, Actor2. Higher scores mean more satisfaction.

Full reference: User journey syntax docs.

---

XY chart

Bar charts and line charts on x/y axes. Useful for time series, distributions, and comparisons.

Where you can use it: available as a template in the mermaid.ai editor, and renders in mermaid.live. Uses the xychart-beta syntax — syntax may evolve in future versions.

Minimum example:

xychart-beta
    title "Sales Revenue"
    x-axis [jan, feb, mar, apr, may, jun]
    y-axis "Revenue (in $)" 4000 --> 11000
    bar [5000, 6000, 7500, 8200, 9500, 10500]
    line [5000, 6000, 7500, 8200, 9500, 10500]

Chart types: use bar for bar chart, line for line chart. Combine both on one chart by including both lines.

Full reference: XY chart syntax docs.

---

Other diagram types

These diagram types are supported in Mermaid but aren't currently in the mermaid.ai editor's template picker. To use them in the editor, click Start with a blank canvas and paste the diagram code. Some have minimum version requirements — check with info if a diagram doesn't render.

ZenUML

An alternative syntax for sequence-style diagrams, with a more code-like feel and richer interaction modeling.

Where you can use it: not in the mermaid.ai template picker — paste into a blank canvas. Renders in mermaid.live.

Minimum example:

zenuml
    title Order Service
    @Actor Customer
    @Boundary OrderController
    @EC2 OrderService
    @Aws_Rds DB

    Customer->OrderController.placeOrder() {
        OrderService.process() {
            DB.save()
        }
    }

Full reference: ZenUML syntax docs.

Treemap

Hierarchical data as nested rectangles, sized proportionally to value. Good for portfolio breakdowns, file size visualization, and budget allocations.

Where you can use it: not in the mermaid.ai template picker — paste into a blank canvas. Renders in mermaid.live. Uses the treemap-beta syntax — syntax may evolve in future versions.

Minimum example:

treemap-beta
"Section 1"
    "Leaf 1.1": 12
    "Section 1.2"
        "Leaf 1.2.1": 12
"Section 2"
    "Leaf 2.1": 20
    "Leaf 2.2": 25

Full reference: Treemap syntax docs.

Radar chart

Multi-axis charts comparing values across several dimensions. Good for skill assessments, product comparisons, and KPI dashboards.

Where you can use it: not in the mermaid.ai template picker — paste into a blank canvas. Renders in mermaid.live. Uses the radar-beta syntax — syntax may evolve in future versions.

Minimum example:

radar-beta
    title Skills assessment
    axis A["Strength"], B["Speed"], C["Skill"], D["Stamina"], E["Smarts"]
    curve a["Player 1"]{75, 80, 90, 70, 95}
    curve b["Player 2"]{65, 95, 70, 85, 60}
    max 100
    min 0

Full reference: Radar chart syntax docs.

Venn diagram (v11.13.0+)

Set-relationship diagrams showing overlap between groups. Common for category analysis, audience segmentation, and feature comparisons.

Where you can use it: not in the mermaid.ai template picker. Renders in mermaid.live. To use in the mermaid.ai editor, your version must be v11.13.0 or higher — check with info. Uses the venn-beta syntax — syntax may evolve in future versions.

Minimum example:

venn-beta
    set A["Designers"]
    set B["Engineers"]
    set C["Product"]
    union A,B
    union B,C
    union A,C
    union A,B,C

Full reference: Venn diagram syntax docs.

Ishikawa diagram (v11.13.0+)

Also called fishbone or cause-and-effect diagrams. Used for root-cause analysis in postmortems, incident retros, sprint reviews, and quality reviews. The classic "6 Ms" categories (Machine, Method, Material, Man, Measurement, Mother Nature) are common in manufacturing; software teams often use Infrastructure, Code, Process, and Tools.

Where you can use it: not in the mermaid.ai template picker. Renders in mermaid.live. To use in the mermaid.ai editor, your version must be v11.13.0 or higher — check with info. Uses the ishikawa-beta syntax — syntax may evolve in future versions.

Minimum example:

ishikawa-beta
    Slow API Response
        Infrastructure
            Underpowered instances
            No CDN
        Code
            N+1 queries
            Unoptimized indexes
            Missing caching
        Process
            No performance budgets
            Reviews skip load testing

Structure: first line is the problem (the "head" of the fish). Top-level indented items become major bones (cause categories). Further indentation creates sub-causes. Nest as many levels as needed.

Full reference: Ishikawa syntax docs. See also our blog post on fishbone diagrams for use cases.

TreeView (v11.14.0+)

File-tree-style hierarchical display. Useful for documenting folder structures, navigation hierarchies, and outline content.

Where you can use it: not in the mermaid.ai template picker. Renders in mermaid.live. To use in the mermaid.ai editor, your version must be v11.14.0 or higher — check with info. Uses the treeView-beta syntax — syntax may evolve in future versions.

Minimum example:

treeView-beta
    "src"
        "components"
            "Button.tsx"
            "Card.tsx"
        "pages"
            "Home.tsx"
        "App.tsx"
    "package.json"
    "README.md"

Structure: hierarchy is determined entirely by indentation. Use quotes around all node names.

Full reference: TreeView syntax docs.

---

More examples and references

• Other examples — additional ready-to-paste examples across diagram types.
• Syntax reference index — entry point for every diagram type's syntax.
• Configuration options — full configuration reference (themes, layout engines, font settings, etc.).
• Theming guide — customizing colors, fonts, and styling.

Need help with a specific diagram type or feature? Contact us with the diagram code that isn't working and the Mermaid version from info — that's almost always enough for us to spot the issue.