Mermaid Journey Map: Syntax, Examples & Templates
Open journey map in the editor
A journey map charts a person’s experience through a process step by step, scoring each step for how it felt. Product teams use it to find the dips — the steps where enthusiasm drops — because those dips are where users give up.
Basic syntax
The declaration is journey, followed by a title. The body is organized into section blocks, which become the phases of the experience. Inside a section, each task line is Task name: score: actor — for example Add to cart: 5: Shopper means the step “Add to cart” was scored 5 out of 5 by the actor “Shopper”. The score drives the height of each point on the chart, and the actor name colors the line, so a diagram with several actors shows several trajectories across the same phases.
Sections, tasks and scores
Scores run 1 to 5 and should reflect the user’s experience, not the step’s importance — a critical step can still be a 2, and that contrast is exactly the insight. The gym signup example earns its keep on “Sign contract: 2”: everything around it is pleasant, and the low point pinpoints where prospects abandon. Keep sections to two or three tasks each so phases stay readable, and name sections as stages of the experience (“Browse”, “Checkout”, “Delivery”) rather than as features. Tasks should be written from the user’s side of the glass: “Track driver”, not “Dispatch webhook”. If you have survey or session-recording data, use it to set scores; if not, scores from a team workshop are still far better than nothing, as long as you label them as estimates.
Common gotchas
The task line needs both colons: Task: 4: Actor. Omitting the actor makes the line invalid, and omitting the score shifts everything one field over, producing a chart with a nonsense score. Scores outside 1–5 render unpredictably. Actor names are matched literally, so “Shopper” and “shopper” create two separate trajectories — pick one spelling and keep it. And do not mix actors within a single task line; each line belongs to exactly one actor, and a shared step should appear once per actor if their experiences differ.
Tips for mobile editing
Short task names and one actor per diagram keep lines short enough to edit comfortably on a phone. Write the sections first, then the tasks, then adjust scores last — scores are the cheapest thing to change and the most likely to change after a discussion. When a journey grows past a dozen tasks, split it at a natural boundary such as “order placed”. The cheatsheet shows the task line grammar.
Journey maps are about felt experience over steps; for plain chronology use a timeline, and for the proportions behind the scores a pie chart shows how steps distribute across categories.
Journey Map templates
Every template opens in the editor with the code pre-filled — edit it on your phone or desktop.
