🚶 Mermaid

User journey

See your product through your users’ eyes

Open this example in the editor Generate one with AI

What is a User journey?

A user journey maps the steps a user takes to accomplish a goal, scored by satisfaction at each step. It instantly reveals friction points in onboarding, checkout or support experiences.

User journeys are made for the wall of a workshop room rather than an architecture document: product, support and design read the same picture and argue about the same low score. Their value is emotional, not technical — a step that works perfectly can still score two. Their limit is that the diagram holds one linear path with one number per step. Drop-off rates and channels live elsewhere.

Live example

Mermaid code

journey
    title Checkout experience
    section Browse
      Find product: 5: Customer
      Compare options: 3: Customer
    section Purchase
      Add to cart: 4: Customer
      Enter payment: 2: Customer
      Confirm order: 5: Customer

Live example

When to use it

Map onboarding and checkout experiences

Identify friction points with satisfaction scores

Align product and support teams on the real user path

Common mistakes

A step with no actor

Writing Find product: 5 renders the step but attaches it to nobody, so it disappears from the actor legend and the row of faces looks incomplete. Every step needs at least one actor after the score.

Actor names must match exactly

Customer and customer are two different actors, each with its own colour and legend entry. The diagram still renders, so the duplicate is easy to miss — copy the name rather than retyping it on every line.

Personas are not step actors

Listing Customer, Support on one step is fine — it names who is involved there. What breaks is running two personas through the same journey: the single score line then averages two different experiences. Draw one journey per persona.

Basic syntax

.mmd

journey
    title My journey
    section Phase
      Step name: 5: Actor

journey title Checkout experience
The title names the goal the user is trying to reach. One journey should cover one goal for one persona; a second persona means a second diagram.
section Purchase
Sections split the journey into phases — browse, decide, pay, receive — and are drawn as a band above the steps they contain, which also groups the score line visually.
Enter payment: 2: Customer
A step is text, then a score from 0 to 5, then the actors, all separated by colons. The score sets the face and the height of the point.
%%{init: {"theme": "forest"}}%%
An init directive on the first line switches the theme, which is the only styling lever a journey offers — there is no per-step or per-section colour.

Questions about this diagram

What do the scores mean?

Each step gets a 0–5 satisfaction score shown as a face. Low scores highlight exactly where users struggle — your improvement backlog, visualized.

Can several actors appear in one journey?

Yes — list multiple actors after the score (e.g. “Checkout: 3: Customer, Support”) to show who is involved at each step.

How do I export a user journey for a workshop deck?

Export PNG at 2× or 4× so the faces stay readable when projected, or SVG for a printed poster. The source stays text, so the diagram can be updated between two sessions in a couple of minutes.

Can a Mermaid journey show drop-off rates or channels?

No. The only quantitative element is the 0–5 score; there are no columns for metrics, channels or touchpoints. Keep those in a table beside the diagram and let the journey carry the emotional shape of the path.

How do I show a user who abandons halfway?

You cannot branch inside a journey — it is one linear path. Model the abandonment as a low-scoring step, and draw the alternative routes in a flowchart next to it when the branching itself is what you are discussing.

What is the difference from a full customer journey map?

A Mermaid journey keeps three things: steps, actors and satisfaction. A classic journey map also carries channels, pain points, opportunities and verbatim quotes. Use the diagram as the spine and put the rest in the surrounding document.

User journey or another diagram type?

User journey or flowchart?

A flowchart shows what the system allows: every branch, every error path. A journey shows what one person actually did and how it felt. Debating whether an edge case is handled is a flowchart question; deciding what to fix first is a journey question.

User journey or timeline?

A journey is ordered by steps, a timeline by dates. The journey repeats for every user and carries a score; the timeline happened once and carries no judgement. Onboarding is a journey; the history of your onboarding redesign is a timeline.

Explore other diagram types

🔀 Flowchart 💬 Sequence diagram 🧩 Class diagram 🗄️ Entity-relationship diagram 🔄 State diagram 📅 Gantt chart 🥧 Pie chart 🧠 Mind map 🌿 Git graph 🕰️ Timeline 🎯 Quadrant chart

Create your User journey now

Describe it in plain language — the AI writes the Mermaid code for you.

Open Mermaid Studio