Title
Add a title to your diagram with the title keyword on its own line. It appears at the top of the rendered diagram.
title User Login Flow
The title is optional but recommended — it makes diagrams self-describing when shared as images or pasted into docs.
Participants & Actors
Declare the boxes at the top of your diagram before writing messages. Order matters — participants appear left to right in the order you declare them.
| Syntax | Description |
|---|---|
| participant Browser | Rectangle box labelled "Browser" |
| actor User | Stick figure — use for humans and external agents |
| participant "Auth Server" as Auth | Long display name, aliased to Auth in messages |
| actor "End User" as U | Stick figure with alias |
Example
actor User participant Browser participant "Auth Server" as Auth participant Database User->Browser: Enter credentials Browser->Auth: POST /login
Tip: If you reference a name in a message before declaring it, it auto-declares. Explicit declaration gives you control over the order.
Message Types (Arrows)
Messages are the arrows between participants. General form: Sender ARROW Receiver: label
A->B: message
Synchronous call
Solid line, filled arrowhead. Sender waits for response.
A-->B: message
Return / response
Dashed line, open arrowhead. Use for replies and async responses.
A->>B: message
Async fire-and-forget
Solid line, open arrowhead. Caller does not wait.
A-->>B: message
Async response
Dashed line, open arrowhead. Async return message.
A-x B: message
Lost message
No response expected — fire-and-forget with explicit X.
A->A: message
Self-call
Loopback arrow for internal processing or self-invocation.
Quick reference table
| Arrow | Line | Arrowhead | Use for |
|---|---|---|---|
| -> | Solid | Filled | Synchronous call |
| --> | Dashed | Open | Response / return |
| ->> | Solid | Open | Async / non-blocking |
| -->> | Dashed | Open | Async response |
Notes
Notes add commentary bubbles to the diagram — useful for explaining a step without cluttering the arrow label.
| Syntax | Description |
|---|---|
| note over A: text | Note above participant A |
| note over A,B: text | Note spanning A and B |
| note left of A: text | Note to the left of A |
| note right of A: text | Note to the right of A |
Example
participant Client participant Server Client->Server: POST /login note over Server: Validates credentials and issues JWT Server-->Client: 200 OK + JWT token note over Client,Server: Session established
Combined Fragments
Fragments wrap messages in labelled boxes that show conditional or repeated behaviour. Each starts with a keyword and ends with end.
loop — Repetition
loop Every 30 seconds Client->Server: GET /heartbeat Server-->Client: 200 OK end
alt — Alternatives (if / else)
Use else to add branches. Only one branch executes at runtime.
alt Login successful Auth-->Browser: JWT token Browser-->User: Redirect to dashboard else Invalid credentials Auth-->Browser: 401 Unauthorized Browser-->User: Show error message end
opt — Optional block
opt User has MFA enabled Auth->User: Send OTP User->Auth: Submit OTP end
group — Custom label
group Checkout flow User->App: Select items App->Payment: Charge card end
Activation Bars
Activation bars (narrow rectangles on a lifeline) show when a participant is actively processing a request. Use activate and deactivate.
Client->Server: POST /login activate Server Server->Database: SELECT user Database-->Server: User record Server-->Client: JWT token deactivate Server
Activation bars are optional but add clarity when showing which participant is "doing work" at each point in the timeline.
Comments
Lines starting with # are comments — not rendered in the diagram. Useful for leaving notes in the source that shouldn't appear in the output.
# This is a comment — not rendered in the diagram participant Alice participant Bob Alice->Bob: Hello # inline comment also works
Complete Example — Everything Together
Combines participants, actors, all message types, a note, alt + opt fragments, and activation bars.
title User Login with MFA actor User participant Browser participant "Auth Server" as Auth participant Database User->Browser: Enter email + password Browser->Auth: POST /api/login activate Auth Auth->Database: SELECT * FROM users WHERE email=? Database-->Auth: User record alt Password matches opt MFA enabled Auth->User: Send OTP via SMS User->Auth: Submit OTP end note over Auth: Signs JWT with 1h expiry Auth-->Browser: 200 OK — JWT + refresh token Browser-->User: Redirect to dashboard else Wrong password Auth-->Browser: 401 Unauthorized Browser-->User: Show error end deactivate Auth
Open the editor → and paste this to see it render live.
See syntax in real-world diagrams
Every feature above appears in these ready-made examples — open any of them in the editor to explore the source:
Frequently asked questions
How do you write a sequence diagram in plain text?
Declare participants with participant Name or actor Name, then write messages: A->B: message. Add title Your Title at the top, and use alt/loop/opt fragments for conditions and loops.
What is the difference between -> and -->?
-> draws a solid arrow (synchronous call — caller waits). --> draws a dashed arrow (response or async message). By UML convention: requests use solid, responses use dashed.
What is the difference between participant and actor?
participant renders as a rectangle — use for systems, services, databases, APIs. actor renders as a stick figure — use for humans or external agents. Both support aliases: actor "End User" as U.
How do you add a loop or condition?
Wrap messages in a fragment: loop Every 30s … end for loops, alt Success … else Failure … end for conditionals, opt Optional step … end for optional blocks.
Is this syntax compatible with Mermaid or PlantUML?
Yes. Sketmi.com can import and export both Mermaid and PlantUML diagrams. Paste a Mermaid sequenceDiagram block or a PlantUML @startuml/@enduml block and it converts to native syntax automatically. You can also export back to Mermaid (.mmd, compatible with GitHub, GitLab, Notion, and Obsidian) or PlantUML (.puml, compatible with Confluence and JetBrains IDEs). See the Mermaid editor guide or PlantUML editor guide for details.
How many participants can a diagram have?
No hard limit, but more than 6–8 participants tends to make diagrams wide and hard to read. For complex systems, split into multiple focused diagrams.