Mermaid UML Diagrams: Supported Types and Limitations

Mermaid can create useful UML diagrams, but it is not a complete UML modeling suite. It has dedicated syntax for sequence, class, and state diagrams. It also renders ER diagrams, which are valuable for data modeling but are not part of UML. Activity diagrams need a flowchart approximation, while Mermaid's dedicated use case syntax requires version 12.0.0 or later.

That distinction matters when you choose a template. Use Mermaid when you want a diagram that stays close to Markdown and code review. Choose a more complete UML tool when formal notation, uncommon relationship types, or model interchange matters more than a small text source.

Version note: OnUML currently renders Mermaid 11.17.2. The Sequence, Class, State, ER, and Flowchart examples on this page work in that runtime. Mermaid's official Use Case Diagram syntax is marked 12.0.0+, so it is described here but not presented as a runnable OnUML example.

Mermaid UML Support at a Glance

The practical answer is simple: Mermaid is a strong fit for common software documentation diagrams, especially sequence, class, and state views. It becomes less suitable when the diagram must behave like a standards-oriented UML model rather than an explanatory visual.

1. Sequence Diagrams: Best for Interactions Over Time

A sequence diagram answers “who calls whom, and in what order?” Mermaid supports actors, participants, messages, activation, loops, alternatives, parallel regions, and notes. The official Mermaid sequence diagram documentation describes this as an interaction diagram that shows process order.

sequenceDiagram
    actor Customer
    participant Storefront
    participant Orders as Order Service
    participant Payment as Payment Gateway

    Customer->>Storefront: Place order
    Storefront->>Orders: Create order
    Orders->>Payment: Authorize payment
    alt Payment approved
        Payment-->>Orders: Authorization ID
        Orders-->>Storefront: Order confirmed
        Storefront-->>Customer: Show confirmation
    else Payment declined
        Payment-->>Orders: Decline reason
        Orders-->>Storefront: Reject order
        Storefront-->>Customer: Request another payment method
    end

Use this diagram when timing and responsibility are the primary questions. For syntax such as loop, par, notes, and activation bars, continue with the Mermaid Sequence Diagram Guide.

2. Class Diagrams: Best for Types and Relationships

Mermaid class diagrams can show classes, attributes, methods, inheritance, realization, association, aggregation, composition, dependency, and multiplicity. That covers many design discussions and documentation needs without requiring a binary modeling file.

classDiagram
    direction LR

    class Order {
        +String id
        +OrderStatus status
        +submit()
    }

    class LineItem {
        +int quantity
        +Money subtotal()
    }

    class Product {
        +String sku
        +Money price
    }

    Order "1" *-- "1..*" LineItem : contains
    LineItem "*" --> "1" Product : references

This is appropriate for a domain overview, an API model, or a design review. Mermaid's class diagram reference documents UML-style members and relationships, but the source is still a diagram description rather than a full UML repository. If you need advanced UML constructs or stricter notation, compare Mermaid and PlantUML class diagrams.

3. State Diagrams: Best for Lifecycles

State diagrams describe how one object changes in response to events. Mermaid supports start and end states, labeled transitions, choices, notes, composite states, forks, joins, and concurrent regions.

stateDiagram-v2
    [*] --> Draft
    Draft --> Submitted : submit
    Submitted --> Approved : approve
    Submitted --> Rejected : reject
    Rejected --> Draft : revise
    Approved --> [*]

This pattern works well for orders, tickets, approvals, connections, and background jobs. Start with the Mermaid State Diagram Online Editor, or review the Mermaid vs PlantUML state diagram comparison when history states or more formal state-machine semantics are required.

4. ER Diagrams: Useful, but Not UML

An entity-relationship diagram models data entities, attributes, relationships, and cardinality. Mermaid has native erDiagram syntax and uses Crow's Foot relationship markers, as documented in its ER diagram reference.

erDiagram
    CUSTOMER ||--o{ ORDER : places
    ORDER ||--|{ LINE_ITEM : contains
    PRODUCT ||--o{ LINE_ITEM : appears_in

    CUSTOMER {
        string id PK
        string email UK
    }

    ORDER {
        string id PK
        string customer_id FK
        string status
    }

    LINE_ITEM {
        string order_id FK
        string product_id FK
        int quantity
    }

    PRODUCT {
        string id PK
        string sku UK
    }

ER diagrams are often grouped with software modeling diagrams, but they are not a UML diagram type. Choose them for database structure and cardinality. Choose a class diagram when the main subject is object behavior, inheritance, or domain types. You can edit the example in the Mermaid ER Diagram Online Editor or compare Mermaid and PlantUML for ER diagrams.

5. Activity Diagrams: Use a Flowchart Deliberately

Mermaid 11.17.2 does not have a dedicated activityDiagram declaration. A flowchart can still communicate actions, decisions, loops, and parallel-looking branches, so it often solves the documentation problem even though it is not a formal UML Activity Diagram.

flowchart TD
    Start([Order received]) --> Validate{Inventory available?}
    Validate -- No --> Reject[Notify customer]
    Validate -- Yes --> Charge[Authorize payment]
    Charge --> Paid{Payment approved?}
    Paid -- No --> Release[Release inventory]
    Paid -- Yes --> Fulfill[Prepare shipment]
    Reject --> End([Closed])
    Release --> End
    Fulfill --> End

Use this approximation when readers need to understand the process rather than audit UML semantics. Do not silently label the result as a standards-complete activity diagram. For forks, joins, swimlanes, interrupts, and other formal workflow constructs, read the Mermaid vs PlantUML Activity Diagram comparison.

6. Use Case Diagrams: Check the Mermaid Version First

Mermaid 12 introduced dedicated use case syntax with actors, use cases, system boundaries, associations, include, extend, and generalization relationships. The declaration begins with usecase-beta, not usecaseDiagram.

That syntax cannot be rendered by this site's current Mermaid 11.17.2 runtime, so copying a Mermaid 12 use case example into the editor will fail. Until OnUML upgrades and validates Mermaid 12, use PlantUML for a use case diagram or describe the user goal with a supported flowchart. This page intentionally avoids a non-working code block.

When Mermaid Is the Right UML Tool

Choose Mermaid when:

• the diagram lives beside Markdown, source code, or an architecture decision record;
• reviewers should see meaningful text changes in Git;
• sequence, class, or state syntax covers the required model;
• fast editing and easy sharing matter more than strict UML completeness;
• the diagram explains one focused idea rather than acting as a central model repository.

Choose PlantUML or a dedicated UML modeling tool when:

• the team needs component, deployment, object, package, timing, or use case diagrams in the current toolchain;
• formal activity semantics, uncommon relationships, or detailed notation are required;
• multiple diagrams must remain synchronized with one underlying model;
• model interchange, validation, or code engineering workflows are part of the requirement.

For a broader decision, the Mermaid vs PlantUML guide compares setup, syntax, supported diagram families, customization, and documentation workflows.

A Practical Way to Choose the Diagram

Start with the question your reader needs answered:

Then create the smallest diagram that answers that question. Mixing object structure, runtime calls, process decisions, and deployment topology into one visual usually produces a diagram that is technically dense but practically unhelpful.

Start Creating a Mermaid Diagram

If the support matrix matches your need, open the specialized editor for a useful default template: Sequence, Class, State, ER, or Flowchart. You can also browse all Mermaid diagram tools before choosing a syntax.

FAQ

Is Mermaid a UML tool?

Mermaid supports several UML diagram families, especially sequence, class, and state diagrams, but it is not a complete UML modeling environment. Treat it as a text-based diagramming tool with useful UML coverage rather than a full implementation of every UML diagram and modeling workflow.

Which UML diagrams does Mermaid support directly?

Mermaid directly supports sequence, class, and state diagrams. Mermaid 12.0.0+ also provides dedicated use case syntax. ER diagrams are supported directly but belong to data modeling rather than UML.

Can Mermaid create an activity diagram?

Mermaid can use a flowchart to express many activity-like processes, including actions, decisions, and loops. The result is a practical approximation, not a dedicated UML Activity Diagram with the full notation and semantics.

Why does Mermaid use case syntax fail in OnUML?

The official use case syntax requires Mermaid 12.0.0 or later. OnUML currently uses Mermaid 11.17.2, so usecase-beta is not yet available in the editor.

Should I use an ER diagram or a class diagram?

Use an ER diagram for database entities, attributes, keys, and cardinality. Use a class diagram for software types, methods, inheritance, composition, and other object-model relationships.

When should I choose PlantUML instead?

Choose PlantUML when the required UML diagram is not supported by the active Mermaid version, when formal activity or deployment notation matters, or when advanced UML relationships and styling outweigh Mermaid's simpler Markdown-oriented workflow.