2020-08-20 19:01:06 +02:00
# Sequence diagrams
2020-07-14 23:25:43 +02:00
2020-11-05 19:16:12 +01:00
**Edit this Page** [![N|Solid ](img/GitHub-Mark-32px.png )](https://github.com/mermaid-js/mermaid/blob/develop/docs/sequenceDiagram.md)
2019-07-12 20:40:54 +02:00
> A Sequence diagram is an interaction diagram that shows how processes operate with one another and in what order.
Mermaid can render sequence diagrams.
2021-11-02 04:18:18 +01:00
```mermaid-example
2019-07-16 21:13:40 +02:00
sequenceDiagram
Alice->>John: Hello John, how are you?
John-->>Alice: Great!
2021-01-21 21:28:47 +01:00
Alice-)John: See you later!
2019-07-16 21:13:40 +02:00
```
2020-04-23 17:39:23 +02:00
2020-09-07 08:02:09 +02:00
```note
A note on nodes, the word "end" could potentially break the diagram, due to the way that the mermaid language is scripted.
2020-06-27 07:46:09 +02:00
2020-09-07 08:02:09 +02:00
If unavoidable, one must use parentheses(), quotation marks "", or brackets {},[], to enclose the word "end". i.e : (end), [end], {end}.
```
2020-06-27 07:46:09 +02:00
2019-07-12 20:40:54 +02:00
## 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:
2021-11-02 04:18:18 +01:00
```mermaid-example
2019-07-16 21:13:40 +02:00
sequenceDiagram
participant Alice
2021-09-18 08:03:34 +02:00
participant Bob
Alice->>Bob: Hi Bob
Bob->>Alice: Hi Alice
2019-07-16 21:13:40 +02:00
```
2020-04-23 17:39:23 +02:00
2021-09-18 08:03:34 +02:00
### 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.
2021-11-02 04:18:18 +01:00
```mermaid-example
2019-07-12 20:40:54 +02:00
sequenceDiagram
2021-09-18 08:03:34 +02:00
actor Alice
actor Bob
Alice->>Bob: Hi Bob
Bob->>Alice: Hi Alice
```
2019-07-12 20:40:54 +02:00
### Aliases
The actor can have a convenient identifier and a descriptive label.
2021-11-02 04:18:18 +01:00
```mermaid-example
2019-07-12 20:40:54 +02:00
sequenceDiagram
participant A as Alice
participant J as John
A->>J: Hello John, how are you?
J->>A: Great!
```
## 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:
2020-04-23 17:39:23 +02:00
| Type | Description |
| ---- | ------------------------------------------- |
| -> | Solid line without arrow |
| --> | Dotted line without arrow |
| ->> | Solid line with arrowhead |
| -->> | Dotted line with arrowhead |
2021-01-21 21:13:15 +01:00
| -x | Solid line with a cross at the end |
| --x | Dotted line with a cross at the end. |
2021-03-09 07:24:03 +01:00
| -) | Solid line with an open arrow at the end (async) |
2021-01-21 21:13:15 +01:00
| --) | Dotted line with a open arrow at the end (async) |
2019-07-12 20:40:54 +02:00
## Activations
It is possible to activate and deactivate an actor. (de)activation can be dedicated declarations:
2021-11-02 04:18:18 +01:00
```mermaid-example
2019-07-12 20:40:54 +02:00
sequenceDiagram
Alice->>John: Hello John, how are you?
activate John
John-->>Alice: Great!
deactivate John
```
There is also a shortcut notation by appending `+` /`-` suffix to the message arrow:
2021-11-02 04:18:18 +01:00
```mermaid-example
2019-07-12 20:40:54 +02:00
sequenceDiagram
Alice->>+John: Hello John, how are you?
John-->>-Alice: Great!
```
Activations can be stacked for same actor:
2021-11-02 04:18:18 +01:00
```mermaid-example
2019-07-12 20:40:54 +02:00
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!
```
## 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:
2021-11-02 04:18:18 +01:00
```mermaid-example
2019-07-12 20:40:54 +02:00
sequenceDiagram
participant John
Note right of John: Text in note
```
It is also possible to create notes spanning two participants:
2021-11-02 04:18:18 +01:00
```mermaid-example
2019-07-12 20:40:54 +02:00
sequenceDiagram
Alice->John: Hello John, how are you?
Note over Alice,John: A typical interaction
```
## 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:
2021-11-02 04:18:18 +01:00
```mermaid-example
2019-07-12 20:40:54 +02:00
sequenceDiagram
Alice->John: Hello John, how are you?
loop Every minute
John-->Alice: Great!
end
```
## 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:
2021-11-02 04:18:18 +01:00
```mermaid-example
2019-07-12 20:40:54 +02:00
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
```
2020-02-24 05:41:47 +01:00
## 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:
2021-11-02 04:18:18 +01:00
```mermaid-example
2020-02-24 05:41:47 +01:00
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!
```
It is also possible to nest parallel blocks.
2021-11-02 04:18:18 +01:00
```mermaid-example
2020-02-24 05:41:47 +01:00
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
```
2022-05-21 09:31:06 +02:00
## 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:
```mermaid-example
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
```
It is also possible to have no options at all
```mermaid-example
sequenceDiagram
critical Establish a connection to the DB
Service-->DB: connect
end
```
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:
```mermaid-example
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
```
2019-07-31 07:24:48 +02:00
## Background Highlighting
2020-02-24 05:49:18 +01:00
2019-07-31 07:24:48 +02:00
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.
2020-04-23 17:39:23 +02:00
2019-07-31 07:24:48 +02:00
```
rect rgb(0, 255, 0)
... content ...
end
```
2020-04-23 17:39:23 +02:00
2019-07-31 07:24:48 +02:00
```
2019-08-28 18:53:49 +02:00
rect rgba(0, 0, 255, .1)
2019-07-31 07:24:48 +02:00
... content ...
end
```
See the examples below:
2021-11-02 04:18:18 +01:00
```mermaid-example
2019-07-31 07:24:48 +02:00
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.
```
2019-11-27 00:34:52 +01:00
## Comments
2019-07-31 07:24:48 +02:00
2019-11-27 00:34:52 +01:00
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
2021-11-11 03:04:40 +01:00
```mmd
2019-11-27 00:34:52 +01:00
sequenceDiagram
Alice->>John: Hello John, how are you?
%% this is a comment
John-->>Alice: Great!
```
2019-07-12 20:40:54 +02:00
2021-02-09 11:01:27 +01:00
## Entity codes to escape characters
It is possible to escape characters using the syntax exemplified here.
2021-11-02 04:18:18 +01:00
```mermaid-example
2021-02-09 11:01:27 +01:00
sequenceDiagram
A->>B: I #9829 ; you!
B->>A: I #9829 ; you #infin ; times more!
```
Numbers given are base 10, so `#` can be encoded as `#35;` . It is also supported to use HTML character names.
2021-03-11 19:33:07 +01:00
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.
2020-02-16 15:26:08 +01:00
## sequenceNumbers
2020-02-24 05:51:15 +01:00
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:
2020-04-23 17:39:23 +02:00
2021-10-31 22:45:41 +01:00
```html
2020-02-16 15:26:08 +01:00
< script >
2022-05-21 09:40:21 +02:00
mermaid.initialize({ sequence: { showSequenceNumbers: true }, });
< / script >
2020-02-16 15:26:08 +01:00
```
It can also be be turned on via the diagram code as in the diagram:
2020-04-23 17:39:23 +02:00
2021-11-02 04:18:18 +01:00
```mermaid-example
2020-02-16 15:26:08 +01:00
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!
```
2021-08-27 19:56:56 +02:00
## 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.
2021-09-11 01:27:07 +02:00
This can be configured by adding one or more link lines with the format:
2021-11-02 04:18:18 +01:00
```
link < actor > : < link-label > @ < link-url >
```
2021-11-11 03:04:40 +01:00
```mmd
2021-08-27 19:56:56 +02:00
sequenceDiagram
participant Alice
participant John
2021-09-11 01:27:07 +02:00
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
2021-08-27 19:56:56 +02:00
Alice->>John: Hello John, how are you?
John-->>Alice: Great!
Alice-)John: See you later!
```
2021-09-11 01:27:07 +02:00
#### 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.
2021-08-27 19:56:56 +02:00
2021-09-11 01:27:07 +02:00
This can be configured by adding the links lines with the format:
2021-08-27 19:56:56 +02:00
2021-11-02 04:18:18 +01:00
```
links < actor > : < json-formatted link-name link-url pairs >
```
2021-08-27 19:56:56 +02:00
2021-09-11 01:27:07 +02:00
An example is below:
2021-08-27 19:56:56 +02:00
2022-03-20 00:42:08 +01:00
```mermaid-example
2021-08-27 19:56:56 +02:00
sequenceDiagram
participant Alice
participant John
2021-09-11 01:27:07 +02:00
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"}
2021-08-27 19:56:56 +02:00
Alice->>John: Hello John, how are you?
John-->>Alice: Great!
Alice-)John: See you later!
```
2019-07-12 20:40:54 +02:00
## Styling
2020-02-13 15:51:00 +01:00
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
2019-07-12 20:40:54 +02:00
### Classes used
2020-04-23 17:39:23 +02:00
| Class | Description |
| ------------ | ----------------------------------------------------------- |
| actor | Style for the actor box at the top of the diagram. |
| text.actor | Styles for text in the actor box at the top of the diagram. |
| actor-line | The vertical line for an actor. |
| messageLine0 | Styles for the solid message line. |
| messageLine1 | Styles for the dotted message line. |
| messageText | Defines styles for the text on the message arrows. |
| labelBox | Defines styles label to left in a loop. |
| labelText | Styles for the text in label for loops. |
| loopText | Styles for the text in the loop box. |
| loopLine | Defines styles for the lines in the loop box. |
| note | Styles for the note box. |
| noteText | Styles for the text on in the note boxes. |
2019-07-12 20:40:54 +02:00
### Sample stylesheet
```css
body {
background: white;
}
.actor {
2020-04-23 17:39:23 +02:00
stroke: #ccccff ;
fill: #ececff ;
2019-07-12 20:40:54 +02:00
}
text.actor {
2020-04-23 17:39:23 +02:00
fill: black;
stroke: none;
2019-07-12 20:40:54 +02:00
font-family: Helvetica;
}
.actor-line {
2020-04-23 17:39:23 +02:00
stroke: grey;
2019-07-12 20:40:54 +02:00
}
.messageLine0 {
2020-04-23 17:39:23 +02:00
stroke-width: 1.5;
stroke-dasharray: '2 2';
marker-end: 'url(#arrowhead)';
stroke: black;
2019-07-12 20:40:54 +02:00
}
.messageLine1 {
2020-04-23 17:39:23 +02:00
stroke-width: 1.5;
stroke-dasharray: '2 2';
stroke: black;
2019-07-12 20:40:54 +02:00
}
#arrowhead {
2020-04-23 17:39:23 +02:00
fill: black;
2019-07-12 20:40:54 +02:00
}
.messageText {
2020-04-23 17:39:23 +02:00
fill: black;
stroke: none;
2019-07-12 20:40:54 +02:00
font-family: 'trebuchet ms', verdana, arial;
2020-04-23 17:39:23 +02:00
font-size: 14px;
2019-07-12 20:40:54 +02:00
}
.labelBox {
2020-04-23 17:39:23 +02:00
stroke: #ccccff ;
fill: #ececff ;
2019-07-12 20:40:54 +02:00
}
.labelText {
2020-04-23 17:39:23 +02:00
fill: black;
stroke: none;
2019-07-12 20:40:54 +02:00
font-family: 'trebuchet ms', verdana, arial;
}
.loopText {
2020-04-23 17:39:23 +02:00
fill: black;
stroke: none;
2019-07-12 20:40:54 +02:00
font-family: 'trebuchet ms', verdana, arial;
}
.loopLine {
2020-04-23 17:39:23 +02:00
stroke-width: 2;
stroke-dasharray: '2 2';
marker-end: 'url(#arrowhead)';
stroke: #ccccff ;
2019-07-12 20:40:54 +02:00
}
.note {
stroke: #decc93 ;
fill: #fff5ad ;
}
.noteText {
2020-04-23 17:39:23 +02:00
fill: black;
stroke: none;
2019-07-12 20:40:54 +02:00
font-family: 'trebuchet ms', verdana, arial;
2020-04-23 17:39:23 +02:00
font-size: 14px;
2019-07-12 20:40:54 +02:00
}
```
## Configuration
Is it 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.
2021-04-30 13:53:02 +02:00
How to use the CLI is described in the [mermaidCLI ](mermaidCLI ) page.
2019-07-12 20:40:54 +02:00
`mermaid.sequenceConfig` can be set to a JSON string with config parameters or the corresponding object.
```javascript
mermaid.sequenceConfig = {
2020-04-23 17:39:23 +02:00
diagramMarginX: 50,
diagramMarginY: 10,
boxTextMargin: 5,
noteMargin: 10,
messageMargin: 35,
mirrorActors: true
2019-07-12 20:40:54 +02:00
};
```
2020-10-14 14:41:15 +02:00
### Possible configuration parameters:
2019-07-12 20:40:54 +02:00
2020-10-14 14:41:15 +02:00
| Parameter | Description | Default value |
2020-04-23 17:39:23 +02:00
| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------ |
2020-10-14 14:41:15 +02:00
| mirrorActors | Turns on/off the rendering of actors below the diagram as well as above it | false |
2020-04-23 17:39:23 +02:00
| bottomMarginAdj | Adjusts how far down the graph ended. Wide borders styles with css could generate unwanted clipping which is why this config param exists. | 1 |
| actorFontSize | Sets the font size for the actor's description | 14 |
2022-02-15 14:21:04 +01:00
| actorFontFamily | Sets the font family for the actor's description | "Open Sans", sans-serif |
| actorFontWeight | Sets the font weight for the actor's description | "Open Sans", sans-serif |
2020-04-23 17:39:23 +02:00
| noteFontSize | Sets the font size for actor-attached notes | 14 |
| noteFontFamily | Sets the font family for actor-attached notes | "trebuchet ms", verdana, arial |
2020-06-11 21:31:59 +02:00
| noteFontWeight | Sets the font weight for actor-attached notes | "trebuchet ms", verdana, arial |
2020-04-23 17:39:23 +02:00
| noteAlign | Sets the text alignment for text in actor-attached notes | center |
| messageFontSize | Sets the font size for actor< - > actor messages | 16 |
| messageFontFamily | Sets the font family for actor< - > actor messages | "trebuchet ms", verdana, arial |
2020-06-11 21:31:59 +02:00
| messageFontWeight | Sets the font weight for actor< - > actor messages | "trebuchet ms", verdana, arial |