Complete Guide to Mermaid.js Diagrams
Learn how to create professional diagrams using simple text-based syntax
What is Mermaid.js?
Mermaid is a JavaScript-based diagramming and charting tool that uses Markdown-inspired text definitions to create and modify diagrams dynamically. It's an open-source project that allows you to generate diagrams from simple text descriptions.
Instead of using complex drawing tools, you write code-like syntax that describes your diagram, and Mermaid renders it as a visual diagram. This approach makes diagrams version-controllable, easy to update, and perfect for documentation.
Mermaid integrates seamlessly with documentation platforms, wikis, and markdown files, making it a favorite tool among developers and technical writers.
Why Use Mermaid.js?
- Version Control: Diagrams are text files, so they can be tracked in Git alongside your code
- Quick Updates: Change a few lines of text instead of redrawing entire diagrams
- Consistency: Mermaid automatically handles layout and styling, ensuring consistent diagrams
- No Design Tools Required: No need for Visio, Lucidchart, or other expensive tools
- Documentation as Code: Keep diagrams in the same repository as your documentation
- Cross-Platform: Works in browsers, Node.js, and integrates with many platforms
- Free and Open Source: No licensing costs, active community support
- Multiple Diagram Types: Supports flowcharts, sequence diagrams, class diagrams, and more
Supported Diagram Types
Mermaid supports a wide variety of diagram types to cover different documentation needs:
Flowchart
Visualize workflows, processes, and decision trees with nodes and edges.
flowchart TD
A[Start] --> B{Decision}
B -->|Yes| C[Process]
B -->|No| D[Alternative]
C --> E[End]
D --> EUse Case: Process flows, algorithms, decision logic
Sequence Diagram
Show interactions between different actors or systems over time.
sequenceDiagram
participant User
participant API
participant DB
User->>API: Request data
API->>DB: Query
DB-->>API: Results
API-->>User: ResponseUse Case: API interactions, system communication, user flows
Class Diagram
Model object-oriented systems with classes, attributes, and relationships.
classDiagram
class Animal {
+String name
+int age
+makeSound()
}
class Dog {
+bark()
}
Animal <|-- DogUse Case: Software architecture, OOP design, database schemas
State Diagram
Represent states and transitions in a system or process.
stateDiagram-v2
[*] --> Idle
Idle --> Loading: Start
Loading --> Success: Complete
Loading --> Error: Fail
Success --> [*]
Error --> Idle: RetryUse Case: State machines, lifecycle management, UI states
Entity Relationship Diagram
Model database structures and relationships between entities.
erDiagram
CUSTOMER ||--o{ ORDER : places
ORDER ||--|{ LINE_ITEM : contains
CUSTOMER {
int id
string name
string email
}Use Case: Database design, data modeling, system architecture
Gantt Chart
Plan and visualize project schedules and timelines.
gantt
title Project Timeline
dateFormat YYYY-MM-DD
section Phase 1
Design :a1, 2024-01-01, 30d
Development :a2, after a1, 45dUse Case: Project planning, sprint timelines, roadmaps
Pie Chart
Show proportional data and percentages visually.
pie title Distribution
"Category A" : 42
"Category B" : 30
"Category C" : 28Use Case: Survey results, market share, resource allocation
Git Graph
Visualize Git branching strategies and commit history.
gitGraph
commit
branch develop
checkout develop
commit
checkout main
merge developUse Case: Git workflow documentation, branching strategies
Getting Started with Mermaid
1. Choose Your Diagram Type
Start by deciding which diagram best represents what you want to show. Each diagram type starts with a specific keyword like 'flowchart', 'sequenceDiagram', or 'classDiagram'.
2. Write the Text Syntax
Use Mermaid's simple syntax to describe your diagram. The syntax is intuitive and reads almost like natural language. For example, 'A --> B' creates an arrow from A to B.
3. Preview Your Diagram
Use our online viewer or any Mermaid-compatible tool to see your diagram rendered in real-time. Make adjustments as needed until you're satisfied.
4. Export and Share
Export your diagram as SVG or PNG for use in presentations, or share a URL with your team. You can also embed Mermaid directly in Markdown files.
Best Practices
- Keep diagrams focused on a single concept or workflow
- Use meaningful labels that describe the actual business logic
- Break complex diagrams into smaller, interconnected diagrams
- Add comments using %% to explain complex sections
- Use consistent naming conventions throughout your diagrams
- Test your diagrams in the target environment before finalizing
- Include direction hints (TD, LR) to control layout when needed
- Use subgraphs to group related nodes in flowcharts
- Leverage styling options sparingly to maintain readability
- Version control your diagram source files alongside your code
Common Use Cases
Software Documentation
Document system architecture, API flows, and component interactions alongside your code.
Project Planning
Create Gantt charts for sprint planning, project timelines, and resource allocation.
Technical Proposals
Visualize proposed solutions, system designs, and architectural decisions.
User Journeys
Map out user flows, customer experiences, and interaction patterns.
Database Design
Model entity relationships, schema structures, and data dependencies.
Process Documentation
Document business processes, workflows, and standard operating procedures.
Educational Materials
Create clear, version-controlled diagrams for tutorials and technical courses.
API Documentation
Illustrate request/response flows, authentication sequences, and endpoint interactions.
Additional Resources
Frequently Asked Questions
Common questions about using the Mermaid Viewer and creating diagrams
Ready to Create Your First Diagram?
Try our free online Mermaid viewer and start creating professional diagrams in minutes.
Open Mermaid Viewer