Mermaid Sequence Diagram: Writing One, and Making It Readable On a Slide
Short answer: a Mermaid sequence diagram starts with the `sequenceDiagram` keyword, declares its participants, and then lists messages between them in the order they happen. The syntax takes about ten minutes to learn. The hard part comes later, when a diagram with fifteen messages has to go on a slide and be understood by people who did not write it.
This guide covers both halves: the syntax, then the presentation problem the syntax creates.
How do you write a Mermaid sequence diagram?
Every sequence diagram opens with the keyword on its own line, then defines who is involved and what they say to each other.
``` sequenceDiagram participant Client participant Gateway participant Auth Client->>Gateway: POST /auth (credentials) Gateway->>Auth: Validate credentials Auth-->>Gateway: JWT token Gateway-->>Client: 200 OK + JWT ```
Four things are doing the work.
Participants. Use `participant` for a service, a system, or a queue. Use `actor` for a human, which renders as a stick figure and is worth doing, because a reader's eye finds the person in the diagram instantly.
Declaring participants explicitly also fixes their left-to-right order. If you skip the declarations, Mermaid orders them by first appearance, which is usually right and occasionally produces a diagram with arrows crossing themselves.
Arrow types. The dashes and angle brackets are not decoration. A solid line with a filled arrowhead, `->>`, is a call. A dotted line, `-->>`, is a return. Getting this right is what makes the diagram readable without a legend: solid lines go out, dotted lines come back.
Activations. Adding `+` and `-` to a message, or using `activate` and `deactivate`, draws a bar on the participant's lifeline showing it is busy. Use them when the point of the diagram is where time is spent. Skip them when it is about what talks to what, because the bars add clutter for no information.
Fragments. `alt` and `else` for branches, `opt` for a conditional block, `loop` for repetition, `par` for concurrency. These are where Mermaid sequence diagrams earn their keep against a hand-drawn arrow chart, and where most people stop reading the documentation too early.
What are the common mistakes?
Too many participants. Five columns is comfortable, seven is a stretch, ten produces a diagram nobody reads. If you genuinely have ten services, draw two diagrams at different altitudes rather than one that is technically correct and practically useless.
Messages that describe implementation rather than intent. `Gateway->>Auth: validateCredentialsAndIssueToken()` tells a reader the method name. `Gateway->>Auth: Validate credentials` tells them what is happening. Method names go stale; intent does not.
Nesting fragments three deep. An `alt` inside a `loop` inside an `opt` is valid Mermaid and unreadable output. Split it.
Forgetting `autonumber`. One line at the top of the diagram numbers every message. It costs nothing and turns "the third call from the left, no, the other one" into "step 7" during a review.
Why does a good sequence diagram fail in a presentation?
This is the part the syntax tutorials do not cover, and it is where most of the pain actually is.
A sequence diagram is a timeline. It encodes order — message one, then two, then three — which is precisely the information a reader has to reconstruct by scanning top to bottom. In a document that works, because the reader controls the pace.
Put the same diagram on a slide and the encoding breaks. Every message appears simultaneously. The audience sees fifteen arrows at once, and a diagram whose entire subject is sequence is delivered with its sequence destroyed. You end up narrating a static image, saying "start at the top", watching people read step twelve while you explain step two.
Splitting it across slides is the usual workaround, and it is worse than it looks. Four slides showing progressively more of the same diagram means four images that must be regenerated every time the flow changes, and in practice three of them quietly stop matching.
What you want is a diagram that reveals each message as you describe it — the same information, delivered at the pace of your explanation. That is the whole argument for animating a sequence diagram, and we made it at length in turning Mermaid diagrams into animated presentation visuals. The wider case for engineers is in animated diagrams for engineers.
Static image or animated build?
| | Static PNG or SVG | Animated build | |---|---|---| | Reader controls pace | Yes, good for docs | No, speaker controls it | | Audience reads ahead | Always | No | | Works in a README | Yes | GIF only, and it loops | | Works on a projector | Legible, but all at once | Builds with the narration | | Effort to update | Re-render | Regenerate from the same source | | Right for | Documentation, PRs, wikis | Presentations, demos, walkthroughs |
The point is not that one is better. It is that a sequence diagram has two jobs, and the artefact that does the documentation job well is the wrong artefact for the room.
Going from definition to an animated version
FluxDiagram's Mermaid converter accepts a `sequenceDiagram` definition directly, reads the participants and messages, and generates an animated version that plays the exchange in the order your source declares. Export as GIF for a loop or MP4 for playback you trigger, then embed it in PowerPoint, Google Slides, or Keynote the way you would insert any media.
Your definition stays in the repository. The slide holds a generated artefact rather than a screenshot, so a flow change means editing the text you already maintain and regenerating, not redrawing four slides by hand.
FAQ
What is the difference between `->>` and `-->>` in Mermaid?
`->>` draws a solid line with a filled arrowhead and conventionally means a call or a request. `-->>` draws a dotted line and means a response or return. Mermaid does not enforce the convention, but every reader expects it, so breaking it makes the diagram harder to read than having no convention at all.
How do I show a conditional branch in a Mermaid sequence diagram?
Wrap the messages in an `alt` block with a condition label, add `else` blocks for the other paths, and close with `end`. Use `opt` instead when there is only one conditional path and no alternative, since it renders as a single labelled box rather than a split one.
How many participants is too many?
Past seven, the diagram usually needs splitting. A practical test: if you cannot read the participant labels when the diagram is scaled to fit a slide, the diagram is too wide for the medium regardless of how correct it is.
Try it with your own flow
If you have a sequence diagram you are about to screenshot into a deck, convert it instead.
Paste your sequenceDiagram code into the converter.
FluxDiagram generates animated diagrams you embed into the deck you already have, in PowerPoint, Google Slides or Keynote.