Mermaid Diagram Types

Purpose

This reference helps authors choose a Mermaid diagram type, use the correct declaration, and provide an accessible alternative that preserves the diagram’s meaning.

Mermaid 11.16.0 is this guide’s reference version. Mermaid adds diagram types and sometimes changes beta declarations. Pin the renderer when the project controls it. When a hosting platform controls the renderer, record the observed version and test the required syntax and output on that platform. Review the official documentation and repeat those tests before upgrading or when the host changes its renderer.

This page is not a record of which narrative generators a particular project has implemented. Keep implementation status in tested, machine-readable project data rather than in a general Mermaid reference.

First Decide Whether a Diagram Is Needed

Use a diagram when relationships, sequence, branching, hierarchy, timing, or spatial grouping materially improve understanding. Prefer ordinary HTML when a short paragraph, list, or table communicates the same information more clearly.

Before choosing a diagram type, identify:

1. the question the diagram must answer;
2. the essential entities, events, values, or states;
3. the essential relationships and their direction;
4. whether position, area, time, or sequence carries meaning;
5. the structured alternative that will preserve that meaning; and
6. the renderer control model, versions, and publishing platforms that must render it.

Do not choose a type merely because its visual style is appealing. Choose the smallest structure that accurately represents the information.

Current Version and Type Status

The Mermaid 11.16.0 source contains 31 user-facing syntax guides when the Railroad guide is counted as one type with four grammar declarations. The documentation sidebar currently links 30 of them and has not yet added the Railroad guide.

Do not publish an unqualified claim that Mermaid supports a fixed number of diagram types. The number depends on the Mermaid version, whether external plugins are counted, and whether related declarations are counted separately.

Mermaid 11.16.0 also has several kinds of status:

• Canonical: the declaration without -beta is accepted by the 11.16.0 detector.
• Beta required: only the declaration ending in -beta is accepted.
• Compatibility alias: both the canonical declaration and the older -beta form are accepted.
• External plugin: the type is documented with Mermaid but must be registered separately.
• Experimental documentation: the syntax page explicitly warns that the type or syntax may change, even if the declaration does not end in -beta.

Status is not uniform across the documentation. For example, the 11.16.0 beta policy accepts canonical sankey, ishikawa, and treemap declarations, while their syntax pages retain experimental or new-type warnings. Treat an explicit page warning as a reason to pin the version when possible and test the target rendering surface carefully.

Verify the Target Rendering Surface

The reference version in this guide identifies the declarations and documentation reviewed while maintaining the guide. It does not guarantee that a publishing platform uses Mermaid 11.16.0 or supports every type listed here.

Treat each rendering surface as a separate target. This includes GitHub.com, each supported GitHub Enterprise Server release, GitHub Pages, local editors, documentation builds, exported SVG or raster images, and PDF conversion. In particular, GitHub Pages does not inherit the Mermaid renderer used by GitHub.com. Its behavior depends on the site’s theme, plug-ins, scripts, and build configuration.

Use the appropriate control model:

• Project-controlled renderer: pin the exact Mermaid version and configuration, validate diagrams in continuous integration, and test before upgrading.
• Platform-managed renderer: use the platform’s documented version probe where available, record the visible result and observation date, and test required capabilities on that exact surface.
• Pre-rendered output: record the tool, version, configuration, and export method used to create the asset. Test both the asset and its embedding context.

A reported version number is useful provenance, but it is not enough by itself. Verify that the target surface:

• recognizes each required declaration and compatibility alias;
• preserves accTitle and accDescr in the final accessible output;
• preserves the visible structured alternative;
• applies acceptable light, dark, high-contrast, zoom, and reflow behavior;
• handles links and any interactive content safely; and
• preserves accessibility through SVG, raster, and PDF export paths.

Keep project support claims in tested, machine-readable data rather than in this general reference. A support record should identify the surface, renderer control model, configured or observed version, discovery method, observation date, declarations and accessibility features tested, fallback, and owner.

Quick Selection Guide

If several types fit, use the one that requires the least visual convention knowledge from the intended audience.

Diagram Type Reference for Mermaid 11.16.0

The declaration is the first non-frontmatter, non-comment content in a Mermaid definition. Declaration spelling and capitalization matter.

Process, Interaction, and Time

Structure, Software, and Systems

Data and Analytical Views

Domain-Specific Views

Choose Data Charts Carefully

Mermaid can render several chart types, but convenience does not make every chart a good choice.

• Use a pie chart only for a small part-to-whole comparison. A sorted bar chart is often easier to compare.
• Do not use a radar chart when precise comparison is important. A grouped bar chart or data table is usually easier to read.
• Use a quadrant chart only when both axes and the coordinates have defined meaning. Do not turn subjective labels into false precision.
• Use a Sankey diagram only when flow quantity is essential. State the units and provide the source, target, and value data.
• A treemap’s area is difficult to compare precisely. Provide the values and hierarchy outside the graphic.
• Limit Venn diagrams to a small number of sets. Complex set relationships are usually clearer in a membership matrix.

Do not rely on color to distinguish a series, category, status, set, or path. Use direct labels, patterns where supported, line styles, markers, position, and a data table. Verify text contrast and the contrast of meaningful graphical objects in every supported theme.

Add Mermaid Accessibility Metadata

Mermaid documents accTitle and accDescr for all diagram and chart types. Use the keywords without comment markers:

flowchart TD
    accTitle: Account recovery decision flow
    accDescr {
      A user submits an email address. If an account is found, the system sends
      a recovery link. Otherwise, the system offers additional help.
    }
    A[Submit email address] --> B{Account found?}
    B -->|Yes| C[Send recovery link]
    B -->|No| D[Offer additional help]

Mermaid comments begin with %%. These lines are ignored as comments and do not provide accessibility metadata:

%%accTitle This is ignored
%%accDescr This is also ignored

Use a colon after accTitle and after a single-line accDescr. For a multi-line description, omit the colon and enclose the description in braces.

accTitle and accDescr improve the generated SVG’s accessible name and description. They do not turn nodes, edges, bars, slices, or regions into a navigable semantic structure. Complex diagrams still need visible structured alternatives.

Match the Alternative to the Type

Sequence example

sequenceDiagram
    accTitle: Password reset request sequence
    accDescr: The website obtains a reset token and asks the email service to send it.
    actor User
    participant Site as Website
    participant Identity as Identity service
    participant Email as Email service
    User->>Site: Request password reset
    Site->>Identity: Create reset token
    Identity-->>Site: Return token
    Site->>Email: Send reset link
    Email-->>Site: Confirm queued message
    Site-->>User: Confirm request

The structured alternative should preserve the message order:

<table>
  <caption>Password reset messages</caption>
  <thead>
    <tr>
      <th scope="col">Step</th>
      <th scope="col">From</th>
      <th scope="col">To</th>
      <th scope="col">Message</th>
    </tr>
  </thead>
  <tbody>
    <tr><td>1</td><td>User</td><td>Website</td><td>Request password reset</td></tr>
    <tr><td>2</td><td>Website</td><td>Identity service</td><td>Create reset token</td></tr>
    <tr><td>3</td><td>Identity service</td><td>Website</td><td>Return token</td></tr>
    <tr><td>4</td><td>Website</td><td>Email service</td><td>Send reset link</td></tr>
    <tr><td>5</td><td>Email service</td><td>Website</td><td>Confirm queued message</td></tr>
    <tr><td>6</td><td>Website</td><td>User</td><td>Confirm request</td></tr>
  </tbody>
</table>

XY chart example

xychart
    accTitle: Completed accessibility reviews by quarter
    accDescr: Completed reviews increased from 12 in quarter one to 27 in quarter four. The data table follows.
    x-axis [Q1, Q2, Q3, Q4]
    y-axis "Completed reviews" 0 --> 30
    bar [12, 18, 21, 27]

<table>
  <caption>Completed accessibility reviews by quarter</caption>
  <thead>
    <tr>
      <th scope="col">Quarter</th>
      <th scope="col">Completed reviews</th>
    </tr>
  </thead>
  <tbody>
    <tr><th scope="row">Q1</th><td>12</td></tr>
    <tr><th scope="row">Q2</th><td>18</td></tr>
    <tr><th scope="row">Q3</th><td>21</td></tr>
    <tr><th scope="row">Q4</th><td>27</td></tr>
  </tbody>
</table>

Tree example

treeView-beta
    accTitle: Documentation repository structure
    accDescr: The repository contains source and examples directories plus configuration and readme files.
    docs/
        source/
            introduction.md
        examples/
            flowchart.md
        README.md

Also expose the hierarchy as a nested list or a native file tree component. Do not assume indentation in the Mermaid source will be available to readers of the rendered SVG.

Narrative Generation and Automation

A project may generate a prose or HTML alternative from Mermaid source, but that is a project feature, not a built-in guarantee of each diagram type.

Use a semantic model

Prefer this pipeline:

1. validate the exact Mermaid source with the pinned renderer or tested target platform;
2. parse the type with version-matched tooling;
3. transform the source into a type-specific semantic model;
4. generate both the visual diagram and its structured alternative from that model;
5. escape untrusted text before inserting it into HTML; and
6. compare the source, diagram, and alternative in automated tests.

Do not use a few regular expressions as a general Mermaid parser. Mermaid supports nesting, quoted text, comments, frontmatter, multiple declarations, and type-specific grammar. A line-based expression that works for a simple example can silently omit branches, cardinality, parallel sequences, composite states, or data values.

Mermaid’s internal parser and diagram database APIs are not a stable semantic interchange contract. If a project depends on internal APIs, pin the Mermaid version when controlled and run regression tests before every upgrade or observed host change.

Define support honestly

For each supported type, document and test:

• accepted declarations and aliases;
• source features the generator understands;
• source features it rejects or cannot preserve;
• the semantic elements and relationships in the output;
• malformed-input behavior;
• HTML escaping and URL sanitization;
• synchronization between visual and alternative output; and
• tests using nested, empty, malformed, and adversarial input.

If the generator cannot preserve the diagram’s essential meaning, require an author-written structured alternative. Do not produce confident but incomplete prose.

Store generator coverage in a tested JSON, YAML, or code manifest. Generate any human-readable support table from that source so the documentation cannot drift from the implementation.

Rendering and Publishing Requirements

The same Mermaid source can produce different results across a live browser renderer, a static site plug-in, Mermaid CLI, an editor preview, a raster export, and a PDF conversion.

For every supported publishing path:

1. record whether the renderer is project-controlled, platform-managed, or used to create pre-rendered output;
2. record the configured or observed Mermaid version, discovery method, configuration, surface, and observation date;
3. parse every diagram during continuous integration when the project controls the build, and run representative capability tests on managed platforms;
4. inspect the final generated SVG or image;
5. verify that title and description relationships survive embedding;
6. verify the visible structured alternative remains adjacent or clearly linked;
7. test light, dark, high-contrast, zoom, and narrow viewport presentation;
8. test keyboard access only where the diagram contains real interaction; and
9. test representative output with screen readers.

A static SVG diagram should not receive tabindex="0" merely so it can be focused. If nodes or links are interactive, implement them as real operable controls or links with visible focus, meaningful names, and documented keyboard behavior.

When the project controls Mermaid, pin an exact version rather than loading an unconstrained major or latest release. Keep Mermaid’s securityLevel: 'strict' default unless a documented and tested requirement justifies a different setting. Treat user-authored Mermaid source, labels, links, configuration, and generated HTML as untrusted input.

Testing Checklist

Source and version

• The renderer control model is documented.
• A project-controlled Mermaid version is pinned exactly.
• A platform-managed version is observed where possible, with the surface, discovery method, and observation date recorded.
• Every declaration is supported by the configured version or tested target platform.
• Beta and external plugin dependencies are documented.
• Every Mermaid block parses in continuous integration when the build is project-controlled; representative diagrams are tested on managed platforms.
• Unsupported syntax fails visibly rather than disappearing silently.

Meaning and alternatives

• The chosen type matches the question the diagram must answer.
• accTitle identifies the diagram concisely.
• accDescr summarizes the essential meaning.
• Complex information has a visible structured alternative.
• The alternative preserves order, hierarchy, direction, values, units, conditions, and relationships as applicable.
• The visual and alternative are generated or reviewed together.

Visual presentation

• Meaning does not depend on color alone.
• Text and meaningful graphical objects meet applicable contrast requirements.
• Labels remain readable at 200% and 400% zoom.
• The diagram does not cause page-wide horizontal scrolling at narrow widths; a local scroll region or alternate view is provided when needed.
• Light, dark, and forced-color presentation have been checked.

Interaction and output

• Static diagrams are not added to the tab order.
• Interactive elements use native links or controls when possible.
• All interaction works with a keyboard and has visible focus.
• Accessible names and descriptions survive the final embedding method.
• Raster and PDF exports include an equivalent alternative in the surrounding document.
• Representative output has been tested with assistive technologies.

Common Failures

• Publishing a fixed count of Mermaid types without naming the Mermaid version.
• Listing a declaration that the deployed renderer does not recognize.
• Treating a sidebar icon as an authoritative stability classification.
• Assuming ZenUML is included in the Mermaid core bundle.
• Calling C4 stable while its own syntax page says it is experimental.
• Using %%accTitle or %%accDescr, which comments out the metadata.
• Assuming accDescr replaces a structured alternative for a complex diagram.
• Flattening a graph into prose that loses direction, branches, cardinality, or values.
• Parsing every diagram type with line-based regular expressions.
• Generating raw HTML from unescaped diagram labels.
• Relying on a chart’s visual area, color, or position without exposing exact data.
• Testing only in the Mermaid Live Editor rather than in the final site.
• Assuming GitHub.com, GitHub Enterprise Server, GitHub Pages, editor previews, and exports use the same renderer or configuration.
• Treating a reported version number as proof that the required syntax, accessibility metadata, themes, and export paths work.
• Loading an unpinned Mermaid release when the project controls the renderer.

Definition of Done

A Mermaid diagram is ready to publish when:

1. the type is appropriate for the information;
2. its declaration parses with the pinned production renderer or tested target platform;
3. beta or plugin dependencies are intentional and documented;
4. it has a useful accTitle and accDescr;
5. a visible structured alternative preserves its essential meaning;
6. color, contrast, zoom, reflow, and theme behavior have been checked;
7. any interaction is keyboard operable and exposes useful semantics;
8. the final embedded or exported output has been tested; and
9. the diagram, its data, and its alternative have a synchronization and review process.

Related Guides

• Mermaid Accessibility Best Practices
• Mermaid Transformation Best Practices
• Charts and Graphs Accessibility Best Practices
• SVG Accessibility Best Practices
• Tables Accessibility Best Practices
• Color Contrast Accessibility Best Practices
• Keyboard Accessibility Best Practices

References

Mermaid

• Diagram syntax and configuration
• Accessibility options
• Mermaid configuration
• Mermaid releases
• Mermaid 11.16.0 release
• ZenUML plugin

GitHub Rendering Surfaces

• Creating diagrams: checking your version of Mermaid
• About GitHub Pages and Jekyll

Accessibility Standards

• WCAG 2.2: Text Alternatives
• WCAG 2.2: Use of Color
• WCAG 2.2: Contrast (Minimum)
• WCAG 2.2: Non-text Contrast
• WCAG 2.2: Reflow
• WAI Images Tutorial: Complex Images
• WAI Tables Tutorial

Mermaid Version Information

This guide uses Mermaid 11.16.0 as its reference version. The reference version identifies the diagram declarations and documentation reviewed while maintaining this guide. It does not claim that every platform uses that version.

The diagram below reports the Mermaid version supplied by the current Markdown hosting platform. It may differ from the version used by GitHub Enterprise Server, GitHub Pages, local builds, editors, exported diagrams, or other rendering services.

info

The result is dynamic diagnostic output, not durable documentation. When version provenance matters, record the visible value together with the surface, discovery method, and observation date in plain text or machine-readable project data.

This document is available under the repository’s MIT License.