Mermaid Sequence Diagram: alt, opt and loop Blocks
Payments fail, cards get declined and services time out. Show those paths in a Mermaid sequence diagram with opt, loop and alt blocks, using an online shop's payment flow in the free Mermaid live editor.
Step by step
When things go wrong
- Payment paths. Real payments go wrong: cards get declined and services time out. A sequence diagram with only the happy path hides that. Here the payment flow of an online shop is written in Mermaid with opt, loop and alt blocks.
- Sequence diagram. In the Mermaid live editor, clear the code and type sequenceDiagram, as one word with a capital D. This tells Mermaid which kind of diagram to draw.
sequenceDiagram
The happy start
- Participants. Add the customer with actor C as Customer, then participant S as Shop and participant P as Payment API. The first message, C->>S: Place order, uses ->> for a solid arrow. The diagram now shows 3 lifelines and 1 message. Next come the paths that only happen sometimes.
actor C as Customer participant S as Shop participant P as Payment API C->>S: Place order
opt
- opt. opt means optional: the messages inside only happen when the condition is true. Type opt No saved card, then S->>C: Ask for card details and C->>S: Enter card details. Close the block with end.
opt No saved card S->>C: Ask for card details C->>S: Enter card details end
loop
- loop. loop repeats the messages inside it. Type loop Up to 3 tries, then S->>P: Charge card and P-->>S: Timeout, then end. The shop tries again when the Payment API times out. The 2 dashes in -->> draw a dotted reply arrow. Each block is drawn as a frame. The keyword sits in the corner, and the condition sits next to it in square brackets, like [Up to 3 tries].
loop Up to 3 tries S->>P: Charge card P-->>S: Timeout end
alt
- alt. After the loop, P-->>S: Payment result sends the answer. Now type alt Approved for the first case, with S-->>C: Order confirmed. Until the block is closed, the live editor greys out the diagram. Type else Declined for the other case, with S-->>C: Ask for another card. Then type one end to close the whole alt block. The alt frame has 2 parts, split by a dashed line. Only one of them happens for each order. The Declined part holds the Ask for another card message. Each part of each block is a scenario, and each scenario can become a test case.
P-->>S: Payment result alt Approved S-->>C: Order confirmedelse Declined S-->>C: Ask for another card end - The whole flow. That is the whole payment flow: an optional card step, a retry loop and 2 outcomes, all written in plain text.
Recap
- The rules. Use opt for steps that only sometimes happen, loop for retries and repeats, and alt with else for either-or outcomes. Close every block with end.
Common mistakes
- Forgetting end. Every opt, loop and alt block needs its own end. Without it the code is not valid, and the live editor greys out the diagram until you add it.
- Putting end after each alt case. In an alt block, else splits the cases. Don't close each case on its own. Put one end after the last case, like after S-->>C: Ask for another card, or the else line ends up outside the block and breaks the diagram.
- Using -> instead of ->>. -> draws a line with no arrowhead. Use ->> for a request like S->>P: Charge card, and -->> for a dotted reply like P-->>S: Timeout.
When a business analyst uses this
In a checkout requirements workshop, a business analyst writes the payment flow in Mermaid while stakeholders watch. They add alt for approved and declined cards and loop for retries. Then each part of each frame becomes an acceptance criterion and a test case, so the unhappy paths are agreed before sign-off.
Questions people ask
Can Mermaid draw sequence diagrams?
Yes. Start the code with sequenceDiagram, list the actors and participants, then write messages like C->>S: Place order. Mermaid draws the lifelines and arrows for you.
How do you show a loop in a Mermaid sequence diagram?
Put the repeated messages between loop and end, with the condition after the word loop, like loop Up to 3 tries. Mermaid draws a frame labelled loop, with the condition in square brackets.
How do you view a Mermaid sequence diagram?
Paste the code into the free Mermaid live editor, which draws the diagram as you type. GitHub also draws Mermaid code that sits inside a ```mermaid code block in a Markdown file.
