Skip to content
On this page

Sequence diagrams

A Sequence diagram is an interaction diagram that shows how processes operate with one another and in what order.

Mermaid can render sequence diagrams.

Code:
mermaid
sequenceDiagram
    Alice->>John: Hello John, how are you?
    John-->>Alice: Great!
    Alice-)John: See you later!
null

Note A note on nodes, the word "end" could potentially break the diagram, due to the way that the mermaid language is scripted.

If unavoidable, one must use parentheses(), quotation marks "", or brackets {},[], to enclose the word "end". i.e : (end), [end], {end}.

Syntax

Participants

The participants can be defined implicitly as in the first example on this page. The participants or actors are rendered in order of appearance in the diagram source text. Sometimes you might want to show the participants in a different order than how they appear in the first message. It is possible to specify the actor's order of appearance by doing the following:

Code:
mermaid
sequenceDiagram
    participant Alice
    participant Bob
    Alice->>Bob: Hi Bob
    Bob->>Alice: Hi Alice
null

Actors

If you specifically want to use the actor symbol instead of a rectangle with text you can do so by using actor statements as per below.

Code:
mermaid
sequenceDiagram
    actor Alice
    actor Bob
    Alice->>Bob: Hi Bob
    Bob->>Alice: Hi Alice
null

Aliases

The actor can have a convenient identifier and a descriptive label.

Code:
mermaid
sequenceDiagram
    participant A as Alice
    participant J as John
    A->>J: Hello John, how are you?
    J->>A: Great!
null

Messages

Messages can be of two displayed either solid or with a dotted line.

[Actor][Arrow][Actor]:Message text

There are six types of arrows currently supported:

TypeDescription
->Solid line without arrow
-->Dotted line without arrow
->>Solid line with arrowhead
-->>Dotted line with arrowhead
-xSolid line with a cross at the end
--xDotted line with a cross at the end.
-)Solid line with an open arrow at the end (async)
--)Dotted line with a open arrow at the end (async)

Activations

It is possible to activate and deactivate an actor. (de)activation can be dedicated declarations:

Code:
mermaid
sequenceDiagram
    Alice->>John: Hello John, how are you?
    activate John
    John-->>Alice: Great!
    deactivate John
null

There is also a shortcut notation by appending +/- suffix to the message arrow:

Code:
mermaid
sequenceDiagram
    Alice->>+John: Hello John, how are you?
    John-->>-Alice: Great!
null

Activations can be stacked for same actor:

Code:
mermaid
sequenceDiagram
    Alice->>+John: Hello John, how are you?
    Alice->>+John: John, can you hear me?
    John-->>-Alice: Hi Alice, I can hear you!
    John-->>-Alice: I feel great!
null

Notes

It is possible to add notes to a sequence diagram. This is done by the notation Note [ right of | left of | over ] [Actor]: Text in note content

See the example below:

Code:
mermaid
sequenceDiagram
    participant John
    Note right of John: Text in note
null

It is also possible to create notes spanning two participants:

Code:
mermaid
sequenceDiagram
    Alice->John: Hello John, how are you?
    Note over Alice,John: A typical interaction
null

Loops

It is possible to express loops in a sequence diagram. This is done by the notation

loop Loop text
... statements ...
end

See the example below:

Code:
mermaid
sequenceDiagram
    Alice->John: Hello John, how are you?
    loop Every minute
        John-->Alice: Great!
    end
null

Alt

It is possible to express alternative paths in a sequence diagram. This is done by the notation

alt Describing text
... statements ...
else
... statements ...
end

or if there is sequence that is optional (if without else).

opt Describing text
... statements ...
end

See the example below:

Code:
mermaid
sequenceDiagram
    Alice->>Bob: Hello Bob, how are you?
    alt is sick
        Bob->>Alice: Not so good :(
    else is well
        Bob->>Alice: Feeling fresh like a daisy
    end
    opt Extra response
        Bob->>Alice: Thanks for asking
    end
null

Parallel

It is possible to show actions that are happening in parallel.

This is done by the notation

par [Action 1]
... statements ...
and [Action 2]
... statements ...
and [Action N]
... statements ...
end

See the example below:

Code:
mermaid
sequenceDiagram
    par Alice to Bob
        Alice->>Bob: Hello guys!
    and Alice to John
        Alice->>John: Hello guys!
    end
    Bob-->>Alice: Hi Alice!
    John-->>Alice: Hi Alice!
null

It is also possible to nest parallel blocks.

Code:
mermaid
sequenceDiagram
    par Alice to Bob
        Alice->>Bob: Go help John
    and Alice to John
        Alice->>John: I want this done today
        par John to Charlie
            John->>Charlie: Can we do this today?
        and John to Diana
            John->>Diana: Can you help us today?
        end
    end
null

Critical Region

It is possible to show actions that must happen automatically with conditional handling of circumstances.

This is done by the notation

critical [Action that must be performed]
... statements ...
option [Circumstance A]
... statements ...
option [Circumstance B]
... statements ...
end

See the example below:

Code:
mermaid
sequenceDiagram
    critical Establish a connection to the DB
        Service-->DB: connect
    option Network timeout
        Service-->Service: Log error
    option Credentials rejected
        Service-->Service: Log different error
    end
null

It is also possible to have no options at all

Code:
mermaid
sequenceDiagram
    critical Establish a connection to the DB
        Service-->DB: connect
    end
null

This critical block can also be nested, equivalently to the par statement as seen above.

Break

It is possible to indicate a stop of the sequence within the flow (usually used to model exceptions).

This is done by the notation

break [something happened]
... statements ...
end

See the example below:

Code:
mermaid
sequenceDiagram
    Consumer-->API: Book something
    API-->BookingService: Start booking process
    break when the booking process fails
        API-->Consumer: show failure
    end
    API-->BillingService: Start billing process
null

Background Highlighting

It is possible to highlight flows by providing colored background rects. This is done by the notation

The colors are defined using rgb and rgba syntax.

rect rgb(0, 255, 0)
... content ...
end
rect rgba(0, 0, 255, .1)
... content ...
end

See the examples below:

Code:
mermaid
sequenceDiagram
    participant Alice
    participant John

    rect rgb(191, 223, 255)
    note right of Alice: Alice calls John.
    Alice->>+John: Hello John, how are you?
    rect rgb(200, 150, 255)
    Alice->>+John: John, can you hear me?
    John-->>-Alice: Hi Alice, I can hear you!
    end
    John-->>-Alice: I feel great!
    end
    Alice ->>+ John: Did you want to go to the game tonight?
    John -->>- Alice: Yeah! See you there.

null

Comments

Comments can be entered within a sequence diagram, which will be ignored by the parser. Comments need to be on their own line, and must be prefaced with %% (double percent signs). Any text after the start of the comment to the next newline will be treated as a comment, including any diagram syntax

Code:
mermaid
sequenceDiagram
    Alice->>John: Hello John, how are you?
    %% this is a comment
    John-->>Alice: Great!
null

Entity codes to escape characters

It is possible to escape characters using the syntax exemplified here.

Code:
mermaid
sequenceDiagram
    A->>B: I #9829; you!
    B->>A: I #9829; you #infin; times more!
null

Numbers given are base 10, so # can be encoded as #35;. It is also supported to use HTML character names.

Because semicolons can be used instead of line breaks to define the markup, you need to use #59; to include a semicolon in message text.

sequenceNumbers

It is possible to get a sequence number attached to each arrow in a sequence diagram. This can be configured when adding mermaid to the website as shown below:

html
<script>
  mermaid.initialize({ sequence: { showSequenceNumbers: true } });
</script>

It can also be be turned on via the diagram code as in the diagram:

Code:
mermaid
sequenceDiagram
    autonumber
    Alice->>John: Hello John, how are you?
    loop Healthcheck
        John->>John: Fight against hypochondria
    end
    Note right of John: Rational thoughts!
    John-->>Alice: Great!
    John->>Bob: How about you?
    Bob-->>John: Jolly good!
null

Actor Menus

Actors can have popup-menus containing individualized links to external pages. For example, if an actor represented a web service, useful links might include a link to the service health dashboard, repo containing the code for the service, or a wiki page describing the service.

This can be configured by adding one or more link lines with the format:

link <actor>: <link-label> @ <link-url>
Code:
mermaid
sequenceDiagram
    participant Alice
    participant John
    link Alice: Dashboard @ https://dashboard.contoso.com/alice
    link Alice: Wiki @ https://wiki.contoso.com/alice
    link John: Dashboard @ https://dashboard.contoso.com/john
    link John: Wiki @ https://wiki.contoso.com/john
    Alice->>John: Hello John, how are you?
    John-->>Alice: Great!
    Alice-)John: See you later!
null

Advanced Menu Syntax

There is an advanced syntax that relies on JSON formatting. If you are comfortable with JSON format, then this exists as well.

This can be configured by adding the links lines with the format:

links <actor>: <json-formatted link-name link-url pairs>

An example is below:

Code:
mermaid
sequenceDiagram
    participant Alice
    participant John
    links Alice: {"Dashboard": "https://dashboard.contoso.com/alice", "Wiki": "https://wiki.contoso.com/alice"}
    links John: {"Dashboard": "https://dashboard.contoso.com/john", "Wiki": "https://wiki.contoso.com/john"}
    Alice->>John: Hello John, how are you?
    John-->>Alice: Great!
    Alice-)John: See you later!
null

Styling

Styling of a sequence diagram is done by defining a number of css classes. During rendering these classes are extracted from the file located at src/themes/sequence.scss

Classes used

ClassDescription
actorStyle for the actor box at the top of the diagram.
text.actorStyles for text in the actor box at the top of the diagram.
actor-lineThe vertical line for an actor.
messageLine0Styles for the solid message line.
messageLine1Styles for the dotted message line.
messageTextDefines styles for the text on the message arrows.
labelBoxDefines styles label to left in a loop.
labelTextStyles for the text in label for loops.
loopTextStyles for the text in the loop box.
loopLineDefines styles for the lines in the loop box.
noteStyles for the note box.
noteTextStyles for the text on in the note boxes.

Sample stylesheet

css
body {
  background: white;
}

.actor {
  stroke: #ccccff;
  fill: #ececff;
}
text.actor {
  fill: black;
  stroke: none;
  font-family: Helvetica;
}

.actor-line {
  stroke: grey;
}

.messageLine0 {
  stroke-width: 1.5;
  stroke-dasharray: '2 2';
  marker-end: 'url(#arrowhead)';
  stroke: black;
}

.messageLine1 {
  stroke-width: 1.5;
  stroke-dasharray: '2 2';
  stroke: black;
}

#arrowhead {
  fill: black;
}

.messageText {
  fill: black;
  stroke: none;
  font-family: 'trebuchet ms', verdana, arial;
  font-size: 14px;
}

.labelBox {
  stroke: #ccccff;
  fill: #ececff;
}

.labelText {
  fill: black;
  stroke: none;
  font-family: 'trebuchet ms', verdana, arial;
}

.loopText {
  fill: black;
  stroke: none;
  font-family: 'trebuchet ms', verdana, arial;
}

.loopLine {
  stroke-width: 2;
  stroke-dasharray: '2 2';
  marker-end: 'url(#arrowhead)';
  stroke: #ccccff;
}

.note {
  stroke: #decc93;
  fill: #fff5ad;
}

.noteText {
  fill: black;
  stroke: none;
  font-family: 'trebuchet ms', verdana, arial;
  font-size: 14px;
}

Configuration

It is possible to adjust the margins for rendering the sequence diagram.

This is done by defining mermaid.sequenceConfig or by the CLI to use a json file with the configuration. How to use the CLI is described in the mermaidCLI page. mermaid.sequenceConfig can be set to a JSON string with config parameters or the corresponding object.

javascript
mermaid.sequenceConfig = {
  diagramMarginX: 50,
  diagramMarginY: 10,
  boxTextMargin: 5,
  noteMargin: 10,
  messageMargin: 35,
  mirrorActors: true,
};

Possible configuration parameters:

ParameterDescriptionDefault value
mirrorActorsTurns on/off the rendering of actors below the diagram as well as above itfalse
bottomMarginAdjAdjusts how far down the graph ended. Wide borders styles with css could generate unwanted clipping which is why this config param exists.1
actorFontSizeSets the font size for the actor's description14
actorFontFamilySets the font family for the actor's description"Open Sans", sans-serif
actorFontWeightSets the font weight for the actor's description"Open Sans", sans-serif
noteFontSizeSets the font size for actor-attached notes14
noteFontFamilySets the font family for actor-attached notes"trebuchet ms", verdana, arial
noteFontWeightSets the font weight for actor-attached notes"trebuchet ms", verdana, arial
noteAlignSets the text alignment for text in actor-attached notescenter
messageFontSizeSets the font size for actor<->actor messages16
messageFontFamilySets the font family for actor<->actor messages"trebuchet ms", verdana, arial
messageFontWeightSets the font weight for actor<->actor messages"trebuchet ms", verdana, arial