3.2 Sequence Diagram Syntax

1. participant vs actor.

  1. Arrows: ->>, -->>, -).

  2. Activation bars and notes.

1. participant vs actor

When you’re writing a sequence diagram in Mermaid, you’ll often see two ways to define who’s involved: participant and actor. They serve similar roles — both show who sends or receives messages — but they have slightly different meanings and uses.

✅ What is a participant?

In Mermaid, participant is the most common keyword for defining an entity in a sequence diagram.

A participant can be:

  • A person (like a User or Admin)

  • A system component (like a Server, API, or Database)

  • Any piece in your process that sends or receives messages

Example:

sequenceDiagram
  participant User
  participant Server
  User->>Server: Request Data

This declares User and Server as participants — and shows a message between them.

✅ What is an actor?

Mermaid also supports actor as a special type of participant. An actor is typically used to visually represent a human or external system — something outside your main system boundary.

The actor keyword:

  • Makes it clearer that this participant is not part of your system’s core components.

  • Adds a little person icon (depending on the renderer) to distinguish it from regular participants.

Example:

Here:

  • User is declared as an actor (a human or external entity).

  • Server is a participant (a system component).

✅ When to Use participant vs actor

Use participant

Use actor

For anything inside your system (APIs, DBs, microservices)

For people, clients, or external systems

When you don’t need a special icon

When you want to show it’s a human or external entity

✅ Can You Mix Them?

Absolutely! It’s common to mix actor and participant in the same diagram — for example, showing a User interacting with your Frontend, Backend, and Database.

Example:

In short:

📌 Use participant for system parts. 📌 Use actor for humans or external systems. This small difference makes your diagram clearer and more accurate for readers.

2. Arrows: ->>, -->>, -)

In Mermaid sequence diagrams, arrows show how messages and actions flow between participants or actors — and the type of arrow you choose helps communicate what kind of interaction is happening.

Let’s break down the three most common arrows you’ll use: ->>, -->>, and -).

✅ 1️⃣ Solid Arrow: ->>

The solid arrow is the most common — it shows a normal message, request, or action sent from one participant to another.

Syntax:

Example:

  • The ->> arrow points from User to Server.

  • Use this for calls, requests, or actions that start the interaction.

✅ 2️⃣ Dashed Arrow: -->>

The dashed arrow usually shows a response, return message, or a passive reply — it makes your sequence clearer by visually separating calls from responses.

Syntax:

Example:

  • The dashed line suggests the message is a reply to a previous action.

  • Use it to make the diagram easy to follow: solid for outgoing requests, dashed for incoming responses.

✅ 3️⃣ Solid Line Without Arrowhead: -)

The -) arrow is used for notes or signals that don’t need a full arrowhead — such as self-calls, activation, or destruction in advanced diagrams. It’s less common for basic sequence diagrams, but good to know.

Syntax:

Example:

  • This draws a line with no arrowhead, sometimes used for signals, calls, or lifecycle changes.

  • You’ll see -) in more complex interactions where the arrowhead isn’t needed.

✅ Practical Example with All Three

Here’s how they work together in context:

  • ->> for requests and actions.

  • -->> for responses.

  • -) for a signal or passive step (logout).

✅ Tips for Clear Arrows

✔️ Use solid arrows (->>) for clear requests. ✔️ Use dashed arrows (-->>) for responses. ✔️ Use -) for signals, lifecycles, or simple notes. ✔️ Keep arrow directions clear — they show who acts and who reacts.

In short:

📌 Arrows are the backbone of your sequence diagram — they show who talks to whom, when, and how. Using the right arrow makes your diagram clear, logical, and easy for anyone to follow.

3. Activation Bars and Notes

In sequence diagrams, it’s helpful not only to show who sends messages but also who is active during each step. Mermaid lets you do this with activation bars — vertical rectangles drawn on top of a participant’s lifeline — and notes, which add extra explanations for clarity.

✅ What Are Activation Bars?

Activation bars show when a participant is active, meaning it’s doing something — like running a process, waiting for a response, or handling a task.

In Mermaid, you use activate and deactivate to control when the bar starts and stops.

✅ Basic Activation Syntax

Example:

What happens here:

  • User sends a request to Server.

  • Server activates when it starts working on the request.

  • Server sends the response back.

  • Server deactivates once it’s done.

This makes it clear when the server is busy.

✅ When to Use Activation Bars

Use activation bars to:

  • Show when a system or service is processing.

  • Visualize nested actions (e.g., an API calls another service).

  • Make it clear when components are waiting vs. active.

They’re optional, but they make complex interactions much easier to follow.

✅ What Are Notes?

Notes help you explain what’s happening at any point in your diagram. They don’t affect the flow — they’re just comments that appear alongside your participants or messages.

✅ Basic Note Syntax

You can attach a note to:

  • A single participant

  • Between two participants

Attach to a participant:

Between participants:

✅ Example: Using Notes

What happens here:

  • A note explains what the user sends.

  • An activation bar shows the server working.

  • A final note describes the whole interaction.

✅ Tips for Activation Bars and Notes

✔️ Keep activation blocks short and clear — match them with what’s actually happening. ✔️ Use notes to clarify complex or important steps. ✔️ Combine them to make your diagram easy for teammates to read — especially when explaining systems to people who aren’t developers.

In short:

📌 Activation bars show when a participant is busy working. 📌 Notes add helpful context so your sequence diagram tells a clear story. Together, they make your diagrams more useful, understandable, and professional.

Previous3.1 Sequence DiagramsNext3.3 Example: API Request

Last updated