Mermaid.js is an open-source JavaScript library that renders diagrams from a simple text syntax. You write a Mermaid code block — for example, 'graph LR; A --> B; B --> C' — and the library renders it as an SVG diagram. It is natively supported in GitHub, GitLab, Notion, Obsidian, and many other Markdown-based tools.

What diagram types does Mermaid support?

Flowcharts (graph LR/TD), sequence diagrams, class diagrams, state diagrams, Gantt charts, entity-relationship diagrams (erDiagram), quadrant charts, requirement diagrams, Gitgraph, mindmaps, and timelines. The supported set grows with each release but is narrower than a general-purpose diagramming tool.

Can I use Mermaid for BPMN or C4 diagrams?

Mermaid has no native BPMN or C4 diagram type. You can approximate a BPMN-like flow using the flowchart or sequence diagram types, but the result will not use BPMN notation (pools, gateways with type markers, BPMN events). C4 diagrams are not supported at all — Structurizr DSL is the code-as-diagram equivalent for C4.

Does Mermaid support custom styling?

Mermaid supports theming via CSS class assignments (classDef) and a built-in theme system (default, dark, forest, neutral). Custom styling is limited — you cannot set per-edge stroke widths, custom node shapes beyond its predefined set, or complex fill gradients. For presentation-quality output, Mermaid diagrams usually require post-processing.

Is Mermaid suitable for large diagrams?

Performance and readability both degrade on large Mermaid diagrams. The text source of a 50-node diagram is difficult to read and edit. The auto-layout engine (Dagre or ELK) can produce poor results for complex graphs — crossing edges, unbalanced layouts, overlapping labels. Manual layout control is limited to subgraph nesting.

Mermaid.js Limitations and Alternatives

Why Mermaid became the default for developer diagrams

Mermaid.js solved a real problem: diagrams that lived in documentation systems fell out of sync with the codebase because updating them required opening a separate tool, redrawing, exporting an image, and uploading it. Mermaid made diagrams as updatable as code — edit the text block, the diagram re-renders on save. GitHub, GitLab, Notion, and Obsidian added native Mermaid support, making it the de facto standard for diagrams in developer workflows. But Mermaid is optimized for code-as-diagram, not for the full range of technical diagramming needs — and teams that push past its defaults run into real limitations.

How to create a mermaid.js diagram with AI

flow-chart.io generates mermaid.js diagrams from plain language in four steps. No notation knowledge required — describe what you need and the AI handles the symbols, layout, and relationships.

Step 1

Describe what you need

Open flow-chart.io and type a plain-language description of the mermaid.js diagram you want. Name the key actors, systems, steps, or relationships. The more specific your description, the more accurate the generated diagram — but even a rough outline produces a solid first draft. You do not need to know any syntax or notation rules.

Step 2

Review the generated diagram

The AI generates a fully editable diagram in seconds, using the correct notation for your domain. Review the nodes, connectors, and labels. Check that the relationships are accurate and the layout is readable. The diagram is a scene graph — every element is an independent object, not a flat image.

Step 3

Edit any element directly

Click any node to rename it, change its type, or update its style. Drag nodes to reposition them. Add new nodes by describing what to add in the refinement panel. Remove elements you do not need. The AI can also refine the diagram for you: "add an error handling path," "split this step into two," "change the data store to a cloud icon."

Step 4

Export in the format you need

Export the finished diagram as SVG for web and design tools, PNG at 2× or 4× resolution for presentations and documentation, PDF for print and client deliverables, JSON to version-control the editable scene graph alongside your code, or Mermaid (.mmd) to embed the diagram as text in GitHub or Notion.

What you can create

Mermaid strengths: version-controllable, works natively in GitHub/GitLab/Notion

Mermaid strengths: no account required, runs from a CDN script tag

Mermaid limitations: no visual editor — you edit the text source only

Mermaid limitations: no BPMN, C4, or cloud architecture notation

Alternative: flow-chart.io generates Mermaid export after AI generation

When to use mermaid.js diagrams

The following situations are the highest-value applications for mermaid.js diagrams in professional environments. Each represents a context where a well-constructed diagram reduces miscommunication, speeds decision-making, or produces a deliverable that would otherwise take hours to create manually.

Use Mermaid: sequence diagrams and flowcharts embedded in Markdown READMEs
Use Mermaid: diagrams that must be version-controlled as text diffs
Use an alternative: BPMN 2.0, C4, UML class diagrams with formal notation
Use an alternative: large diagrams where auto-layout produces poor results
Use an alternative: diagrams that need visual editing without touching syntax

In each case, the diagram is not decoration — it is the primary artifact that the team or stakeholder actually uses to make a decision, approve a design, or onboard a new member.

Best practices for mermaid.js diagrams

Experienced practitioners consistently apply a small set of principles that separate diagrams people actually use from ones that get ignored after the meeting. Apply these to every mermaid.js diagram you create.

Start with the happy path — the primary successful flow through the mermaid.js — before adding error handling, edge cases, and alternative routes. A diagram that shows the happy path clearly is immediately useful; one that tries to show every edge case first becomes unreadable.
Name every element specifically. "Process order" is more useful than "Process" and "Validate payment with Stripe" is more useful than "Payment validation." Specific names let readers understand the diagram without needing a separate explanation.
Use the right level of detail for your audience. A mermaid.js diagram for a business stakeholder should show roles and outcomes, not implementation details. A diagram for engineers should show system boundaries, technologies, and data flows. When in doubt, create two versions.
Export a JSON copy of every diagram you want to maintain over time. The JSON export contains the complete typed scene graph — you can re-import it to continue editing after weeks or months. This is your version-controllable source of truth.

AI mermaid.js generation vs. manual diagramming

Both approaches produce editable diagrams, but they differ significantly in where time is spent and what expertise is required. Use this comparison to decide which approach fits your team's workflow.

Aspect	flow-chart.io (AI)	Manual diagramming
Time to first draft	Under 60 seconds from a plain-language description	20–60 minutes drawing and connecting shapes
Notation accuracy	Standards enforced automatically (gateway rules, C4 zoom levels, ERD cardinality)	Depends on practitioner knowledge; violations are common
Editability	Every element is a live object — click to edit any node or connector	All elements are already individually editable by design
Iteration speed	Describe the change in plain language; AI updates the diagram in seconds	Manual drag, delete, and reconnect for each change
Export formats	SVG, PNG 2×/4×, PDF, JSON, Mermaid — all from one click	Depends on the tool; some require additional steps per format
Learning curve	None — describe in English, AI handles notation	Notation-specific for each diagram type (BPMN, UML, C4)

Related guides

These guides cover diagram types that are commonly used alongside mermaid.js diagrams, or that share similar audiences and use cases.

Sequence Diagram Flowchart Maker C4 Model Diagram

Frequently asked questions

What is Mermaid.js?: Mermaid.js is an open-source JavaScript library that renders diagrams from a simple text syntax. You write a Mermaid code block — for example, 'graph LR; A --> B; B --> C' — and the library renders it as an SVG diagram. It is natively supported in GitHub, GitLab, Notion, Obsidian, and many other Markdown-based tools.
What diagram types does Mermaid support?: Flowcharts (graph LR/TD), sequence diagrams, class diagrams, state diagrams, Gantt charts, entity-relationship diagrams (erDiagram), quadrant charts, requirement diagrams, Gitgraph, mindmaps, and timelines. The supported set grows with each release but is narrower than a general-purpose diagramming tool.
Can I use Mermaid for BPMN or C4 diagrams?: Mermaid has no native BPMN or C4 diagram type. You can approximate a BPMN-like flow using the flowchart or sequence diagram types, but the result will not use BPMN notation (pools, gateways with type markers, BPMN events). C4 diagrams are not supported at all — Structurizr DSL is the code-as-diagram equivalent for C4.
Does Mermaid support custom styling?: Mermaid supports theming via CSS class assignments (classDef) and a built-in theme system (default, dark, forest, neutral). Custom styling is limited — you cannot set per-edge stroke widths, custom node shapes beyond its predefined set, or complex fill gradients. For presentation-quality output, Mermaid diagrams usually require post-processing.
Is Mermaid suitable for large diagrams?: Performance and readability both degrade on large Mermaid diagrams. The text source of a 50-node diagram is difficult to read and edit. The auto-layout engine (Dagre or ELK) can produce poor results for complex graphs — crossing edges, unbalanced layouts, overlapping labels. Manual layout control is limited to subgraph nesting.