How to Use Mermaid for Uml Diagrams: a Complete Tutorial

UML diagrams help teams communicate how software works but traditional diagramming tools can be slow and frustrating. You spend time dragging boxes, drawing arrows, and re-aligning everything when something changes. Mermaid solves this by letting you write diagrams using plain text syntax. You describe the structure in code, and Mermaid renders it as a clean UML diagram. If you already write documentation in Markdown or keep diagrams in version control, this approach saves real time and reduces friction.

What is Mermaid and how does it work for UML?

Mermaid is a JavaScript-based diagramming library that generates diagrams from text-based syntax. It's open-source, widely supported, and integrates with platforms like GitHub, GitLab, Notion, and many documentation tools. For UML specifically, Mermaid supports several diagram types including class diagrams, sequence diagrams, state diagrams, and entity-relationship diagrams.

The core idea is simple: you write a few lines of structured text that describe your system, and Mermaid turns that into a visual diagram. No mouse clicking. No pixel alignment. When your code changes, you update a few lines instead of redrawing the whole thing.

Which UML diagram types does Mermaid support?

Mermaid doesn't cover every UML diagram in the official specification, but it handles the ones most developers and architects use regularly:

Class diagrams show classes, their attributes, methods, and relationships like inheritance and association
Sequence diagrams illustrate how objects or components interact over time
State diagrams represent different states of an object and transitions between them
Entity-relationship diagrams model database structures and relationships
Use case diagrams show actors and their interactions with system features

Not every UML diagram type is available. For example, Mermaid doesn't natively support activity diagrams in their full UML form, though you can use flowcharts as a close alternative. If you're looking for practical flowchart code examples, those work well for mapping workflows and processes.

How do you write your first UML class diagram in Mermaid?

Class diagrams are one of the most common UML diagrams people create with Mermaid. Here's the basic syntax:

You start with the classDiagram keyword, then define classes and their relationships. A simple example might look like this:

classDiagram
 class Animal {
 +String name
 +int age
 +makeSound()
 }
 class Dog {
 +fetch()
 }
 class Cat {
 +purr()
 }
 Animal <|-- Dog
 Animal <|-- Cat

This creates a parent class Animal with two child classes. The <|-- symbol represents inheritance. Public members use +, private members use -, and protected members use #.

You can also define different relationship types:

<|-- inheritance
-- composition
o-- aggregation
--> association
..> dependency

How do you create a sequence diagram in Mermaid?

Sequence diagrams show how different parts of your system communicate. They're especially useful for documenting API flows, authentication processes, or multi-service interactions.

The syntax uses sequenceDiagram as the starting keyword. You define participants and then describe messages between them:

sequenceDiagram
 participant User
 participant Frontend
 participant API
 participant Database

 User->>Frontend: Click login button
 Frontend->>API: POST /auth/login
 API->>Database: Query user credentials
 Database-->>API: Return user record
 API-->>Frontend: Return auth token
 Frontend-->>User: Show dashboard

Arrow direction matters. Solid arrows (->>) represent requests, while dashed arrows (-->>) represent responses. You can also add activation boxes, loops, conditionals, and notes to make your diagrams more detailed.

For a complete walkthrough on setting up your diagrams from scratch, the Mermaid diagram tutorial covers the basics step by step.

Where can you render Mermaid diagrams?

You have several options for viewing and editing Mermaid diagrams:

GitHub and GitLab both render Mermaid code blocks in Markdown files and pull request descriptions automatically
The Mermaid Live Editor a browser-based tool at mermaid.live where you can write and preview diagrams in real time
VS Code extensions extensions like "Mermaid Markdown Syntax Highlighting" and "Mermaid Preview" let you work directly in your editor
Notion, Obsidian, and Typora these tools have built-in or plugin-based Mermaid support
Mermaid CLI a command-line tool for generating diagram images (SVG or PNG) from .mmd files

Most developers start with the live editor to experiment, then move to embedding Mermaid blocks in their project documentation.

What are common mistakes when writing Mermaid UML diagrams?

Mermaid's syntax is straightforward, but certain issues trip people up:

Forgetting indentation. Mermaid is sensitive to whitespace in some contexts. Nested elements inside conditions or loops in sequence diagrams need consistent indentation.
Using special characters without escaping. Class names or labels with parentheses, quotes, or angle brackets can break rendering. Wrap problematic text in quotes.
Confusing relationship arrows. Mixing up <|-- (inheritance) with --|> (which is invalid) is a common error. The arrow always points from child to parent.
Overloading a single diagram. Cramming too many classes or participants into one diagram makes it unreadable. Split complex systems into multiple smaller diagrams.
Not testing rendering. Syntax that looks correct might not render on every platform. Always preview your diagram in the tool your audience will use.

How do you keep Mermaid UML diagrams maintainable?

Treat your diagrams like code. Store them in version control alongside the source files they describe. When you refactor a class, update the diagram in the same pull request.

Use comments (lines starting with %%) to explain non-obvious choices in complex diagrams. Name your participants and classes consistently with how they appear in your actual codebase. This makes it easier for other developers to cross-reference the diagram with the implementation.

For larger projects, consider breaking your architecture into multiple diagrams one per service, one per domain, or one per user flow. The advanced Mermaid diagram techniques guide covers strategies for managing diagrams across bigger codebases.

Can Mermaid replace dedicated UML tools?

For most teams, Mermaid handles the 80% case well. If your primary need is documenting class structures, API interactions, and system flows in a way that lives with your code, Mermaid is a strong fit.

However, it has limits. Mermaid doesn't support every UML diagram type, and fine-grained visual control (custom colors, precise layouts, complex styling) is limited compared to tools like Lucidchart, PlantUML, or draw.io. If you need pixel-perfect diagrams for formal documentation or presentations, a dedicated tool might serve you better.

The trade-off is speed. A Mermaid diagram that takes two minutes to write would take fifteen minutes to draw manually. And because it's text, you can diff changes in Git, which is impossible with image-based diagrams.

Quick checklist: getting started with Mermaid UML diagrams

Pick your diagram type class diagram, sequence diagram, state diagram, or ER diagram based on what you need to communicate
Write the syntax start with the diagram keyword and define your elements
Preview in the live editor test your code at mermaid.live before adding it to docs
Embed in your documentation add the Mermaid code block to your Markdown file, README, or wiki
Commit and version store diagrams in Git so they evolve with your code
Review for readability if a diagram has more than 15-20 elements, consider splitting it up

Start with a single class or sequence diagram for a feature you're currently building. Once you see how quickly it fits into your workflow, expanding to other diagram types becomes natural.