Mermaid vs PlantUML Sequence Diagrams: Syntax Differences, Examples, and Choosing the Right Tool

This article focuses only on the visual expressive power of sequence diagrams. It does not cover broader tool differences such as Markdown support, documentation platform integration, ecosystem plugins, or rendering services. For those topics, see the series overview: Mermaid vs PlantUML: Which diagram-as-code tool should you choose in 2026?.

With that scope in mind, the conclusion is straightforward: both tools can handle 90% of everyday sequence diagram needs. PlantUML has more sequence diagram features, but most regular interaction diagrams do not need those advanced capabilities. If you only look at visual expression, the basic difference between Mermaid and PlantUML is small.

Both tools describe the order of system interactions as text, and both support common elements such as alt, loop, par, activation, notes, and actors. What really affects the diagram is usually not "can this tool draw a conditional branch?" It is whether the diagram needs clearer return semantics, more explicit participant types, more complex lifecycles, more natural fragment references, or better support for splitting long flows.

A more accurate way to think about it is:

Mermaid wins on direct expression. For common request chains, business branches, parallel processing, and short call stacks, its syntax is clear enough and the resulting diagrams are easy to read. If the diagram does not involve complex return layers, object lifecycles, or multi-stage pagination, Mermaid usually will not be the bottleneck.

PlantUML wins on finer semantics. It is not stronger because of basic constructs like alt or loop; Mermaid supports those too. PlantUML's advantage is its more complete support for return semantics, participant types, auto-activation, pagination, referenced fragments, and diagram styling, which makes it better for deep call stacks, multi-stage flows, and complex lifecycles.

So this article will not repeat what the Mermaid vs PlantUML overview already covers, such as Markdown friendliness, tooling integration, or team collaboration cost. The comparison below focuses only on sequence diagram capabilities.

This article is based on the official documentation and compares code and visual output through concrete examples:

• Mermaid Sequence Diagram documentation
• PlantUML Sequence Diagram documentation

Core differences in Mermaid vs PlantUML sequence diagrams

One-sentence summary:

Mermaid's core sequence diagram capabilities are already complete; PlantUML's advantage is finer diagram semantics and better long-diagram organization, not basic control syntax.

Mermaid can also support complex logic diagrams

Many people assume Mermaid breaks down as soon as a diagram becomes complex, especially when they see alt, loop, or par and immediately switch to PlantUML. That assumption is not accurate. Mermaid's official sequence diagram syntax supports alt, opt, loop, par, critical, break, and other control fragments, which is enough for most business process explanations.

Here is a payment flow: if items are available, the system charges the card; if payment succeeds, it saves the order and publishes a message; if payment fails, it releases the inventory; if items are out of stock, it returns immediately.

Mermaid code and diagram

sequenceDiagram
  autonumber
  actor User
  participant Web
  participant API
  participant Inventory
  participant Payment
  participant DB
  participant Queue
  participant Email

  User->>Web: Submit order
  Web->>API: POST /orders
  activate API
  API->>Inventory: Reserve items

  alt items available
    Inventory-->>API: Reserved
    API->>Payment: Charge card

    alt payment success
      Payment-->>API: Payment confirmed
      API->>DB: Save paid order
      API->>Queue: Publish OrderPaid
      Queue-->>Email: Send confirmation
      API-->>Web: Show success
    else payment failed
      Payment-->>API: Payment declined
      API->>Inventory: Release items
      API-->>Web: Show payment error
    end
  else out of stock
    Inventory-->>API: Not available
    API-->>Web: Show out of stock
  end
  deactivate API

PlantUML code and diagram

@startuml
autonumber
actor User
participant "Web App" as Web
participant "Order API" as API
participant "Inventory Service" as Inventory
participant "Payment Service" as Payment
database "Database" as DB
queue "Message Queue" as Queue
participant "Email Service" as Email

User -> Web: Submit order
Web -> API: POST /orders
activate API
API -> Inventory: Reserve items

alt items available
  Inventory --> API: Reserved
  API -> Payment: Charge card

  alt payment success
    Payment --> API: Payment confirmed
    API -> DB: Save paid order
    API -> Queue: Publish OrderPaid
    Queue -> Email: Send confirmation
    API --> Web: Show success
  else payment failed
    Payment --> API: Payment declined
    API -> Inventory: Release items
    API --> Web: Show payment error
  end
else out of stock
  Inventory --> API: Not available
  API --> Web: Show out of stock
end
deactivate API
@enduml

Mermaid can also show the full sequence flow clearly. It is not only for simple diagrams; for common multi-branch, multi-participant flows, Mermaid is already expressive enough.

PlantUML can show participant types more explicitly

Now look at a very common sequence diagram scenario: a user clicks checkout, the web app calls an API, the API writes to the database, and the system returns success. This example shows the difference in how the two tools express participant types.

Mermaid code and diagram

sequenceDiagram
  actor User
  participant Web
  participant API
  participant DB

  User->>Web: Click checkout
  Web->>API: POST /orders
  API->>DB: Insert order
  DB-->>API: Order saved
  API-->>Web: 201 Created
  Web-->>User: Show confirmation

PlantUML code and diagram

@startuml
actor User
participant "Web App" as Web
participant "Order API" as API
database "Database" as DB

User -> Web: Click checkout
Web -> API: POST /orders
API -> DB: Insert order
DB --> API: Order saved
API --> Web: 201 Created
Web --> User: Show confirmation
@enduml

PlantUML's advantage is that participant types are more explicit, for example database "Database" as DB. When readers need to quickly distinguish services, databases, queues, and boundary systems, this visual semantics becomes valuable.

PlantUML has better long-diagram organization

Where PlantUML really pulls ahead in sequence diagrams is long-diagram organization and precise semantics. The following example includes several things that Mermaid cannot express as naturally: ref over referenced fragments, return semantics, newpage pagination, title, and footer.

PlantUML code and diagram

@startuml
title Checkout Sequence
footer OnUML Architecture Review - Sequence Diagram
autonumber
autoactivate on

actor User
participant "Web App" as Web
participant "Order API" as API
participant "Payment Service" as Payment
database "Database" as DB

User -> Web: Submit order
Web -> API: POST /orders

ref over API, Payment
  Shared payment authorization flow
end ref

API -> Payment: Authorize payment
return Authorization result

alt authorized
  API -> DB: Save paid order
  return Order id
  API --> Web: Show success
else declined
  API --> Web: Show payment error
end

newpage Fulfillment handoff
API -> DB: Load order
return Order details
API --> Web: Show fulfillment status
@enduml

Mermaid approximation

sequenceDiagram
  autonumber
  actor User
  participant Web
  participant API
  participant Payment
  participant DB

  User->>Web: Submit order
  Web->>API: POST /orders

  Note over API,Payment: Shared payment authorization flow

  API->>Payment: Authorize payment
  Payment-->>API: Authorization result

  alt authorized
    API->>DB: Save paid order
    DB-->>API: Order id
    API-->>Web: Show success
  else declined
    API-->>Web: Show payment error
  end

  Note over API,Web: Fulfillment handoff starts here
  API->>DB: Load order
  DB-->>API: Order details
  API-->>Web: Show fulfillment status

Why is this scenario a better fit for PlantUML?

Mermaid can approximate this diagram, but the semantics are different:

• Mermaid uses Note over to simulate a referenced fragment, while PlantUML has ref over, which behaves more like a formal UML fragment reference.
• Mermaid usually writes returns manually with arrows like Payment-->>API; PlantUML's return goes back to the latest activation point, making the semantics clearer.
• Mermaid does not have an equally natural newpage capability for long diagrams; PlantUML is better for splitting one long flow into consecutive pages.
• PlantUML's title, footer, and skinparam are better for controlling titles, footers, and overall visual styling.

This is PlantUML's real advantage in sequence diagrams: not whether it can draw conditional branches, but whether it can express long flows, deep call stacks, and reusable fragments more clearly.

Sequence diagram recommendations

Choose Mermaid for sequence diagrams when the diagram focuses on:

• Showing one API request chain.
• Explaining a business branch, such as payment success or failure.
• Showing simple parallel processing, such as inventory, risk, and shipping checks running at the same time.
• Helping readers quickly understand the order of interactions.
• Staying reasonably short, ideally within one screen or a small amount of scrolling.

Choose PlantUML for sequence diagrams when the diagram focuses on:

• Showing multi-layer call stacks where return relationships matter.
• Marking a flow as a ref over referenced fragment.
• Exporting one diagram in multiple stages with newpage.
• Expressing object creation, destruction, auto-activation, and complex lifecycles.
• Producing stable titles, footers, numbering, and styling.

FAQ

Does Mermaid support alt in sequence diagrams?

Yes. Mermaid's official sequence diagram syntax supports alt, opt, loop, par, critical, break, and other control fragments. Do not assume Mermaid is insufficient just because your diagram has conditional branches.

Is PlantUML always better than Mermaid for complex flows?

Not always. If "complex" only means more branches or more participants, Mermaid can handle it. PlantUML is better for another kind of complexity: important return relationships, deep call stacks, ref over referenced fragments, newpage pagination, or diagrams that need to become architecture review and design archive materials.

If you only compare visual capabilities, how should you choose between Mermaid and PlantUML?

If the diagram focuses on request chains, business branches, simple parallelism, and short-to-medium flows, Mermaid is usually enough. If the diagram focuses on deep call stacks, explicit returns, object lifecycles, referenced fragments, pagination, or consistent styling, PlantUML is stronger.

Final conclusion:

For sequence diagrams, Mermaid and PlantUML are very close in basic capability. Mermaid is better for short to medium interaction explanations; PlantUML is better for formal sequence diagrams with complex return relationships, complex lifecycles, referenced fragments, or pagination.

You can use both Mermaid and PlantUML modes in the OnUML editor, and copy the examples above to compare the results.