Mermaid User Journey Syntax & Examples
Reference for Mermaid user journey syntax — journey keyword, title, sections, and task lines with satisfaction scores and actors. Copy-paste examples for onboarding, checkout, and support flows.
Syntax reference, layout guidance, and ready-to-open examples for this diagram type.
A syntax reference for Mermaid's `journey` grammar — read this when you need the exact format for task lines, satisfaction scores, or actor lists, then try the result in the editor.
View Mermaid sourcePlain-text diagram syntax — copy or edit directly.
1journey2 title New user onboarding3 section Discover4 Land on homepage: 5: New user5 Compare plans: 4: New user6 section Sign up7 Create account: 3: New user8 Verify email: 2: New user9 section First success10 Import first diagram: 6: New user11 Share with team: 7: New user, TeammateWhat is a Mermaid user journey
A user journey diagram maps the steps a person takes through a process and scores how each step feels. Each task carries a satisfaction score from 1 (frustrating) to 7 (delightful), and the scores trace a curve across the diagram — the emotional shape of the experience at a glance. It is the right diagram when the question is where-does-the-experience-hurt: onboarding flows, checkout funnels, support interactions, first-run experiences. Use a flowchart instead when the process branches on decisions, and a sequence diagram when the content is messages between systems rather than a person's experience. Journeys are the only Mermaid type that encodes sentiment, which is exactly what makes them useful in UX reviews.
Basic syntax — journey + title + sections
Every Mermaid user journey starts with the `journey` keyword. Add a chart title with `title <Text>` on the next line. Then declare sections with `section <Phase Name>` — each section groups the tasks of one phase (Discover, Sign up, First use). Under each section, write one task per line. Sections render as labelled bands across the top, and the tasks inside them keep their source order left to right.
- `journey` — diagram type keyword (always first)
- `title <Text>` — chart title (appears at the top)
- `section <Phase Name>` — groups the tasks of one phase
- One task per line inside each section
Task format — name, score, actors
A task line has three colon-separated parts: `Task name: <score>: <actors>`. The name is free text and becomes the task label. The score is an integer from 1 to 7 — higher is happier — and drives both the face icon on the task and the height of the satisfaction curve. The actors are a comma-separated list of who performs the task (`Me`, `Support agent`, `Cat`); they are optional, and the same actor names are collected into a legend. A typical line reads `Find the signup form: 3: New user`. Keep scores honest — the value of the diagram is the dips, and a journey where everything scores 6 tells the reader nothing.
- `Task name: 5: Me` — three parts separated by colons
- Score is an integer 1–7; higher is happier
- Actors are comma-separated and optional
Reading the satisfaction curve
The score does double duty. Each task shows a face icon — happy for high scores, neutral for the middle, sad for low ones — and the tasks themselves sit higher or lower so the whole diagram reads as a curve. A healthy onboarding journey starts mid, dips at the first hard step, and climbs to a high finish. A journey that sags in the middle and never recovers is a redesign argument drawn in one picture. When you present one of these, narrate the lowest point first: that is the step your audience will ask about.
When to pick a different chart
Journeys are deliberately linear — no branches, no parallel paths, no loops. When the process genuinely branches ("if payment fails, retry"), use a flowchart and keep the journey for the happy path. When the content is which-system-calls-which, use a sequence diagram. When the story is what-happened-when rather than how-it-felt, use a timeline. A useful rule: if you cannot honestly attach a satisfaction score to a step, that step probably belongs in a different diagram type.
Common patterns & gotchas
Three patterns cover most real journeys. New-user onboarding (Discover / Sign up / First success) is the most common — three sections, scores dipping at the friction step. Checkout funnel (Browse / Decide / Pay / Confirm) is the second — usually exposes a low score around payment details. Support interaction (Hit problem / Find help / Resolve) is the third — starts low by definition and should end high. The most common syntax gotcha: the score must be a bare number — `Make tea: high: Me` is invalid and the line is skipped with a warning, so write `Make tea: 5: Me`. Second gotcha: a task line needs at least the name and the score; actors can be omitted but the score cannot.
- Score must be a number 1–7 — words like `high` make the line invalid
- Actors are optional; the score is not
- Branching flows belong in a flowchart — journeys are linear by design