---
description: >-
  Learn how to craft user journey diagrams in Mermaid to visualize user
  experiences, interactions, and workflows for applications or systems.
---

# User Journey Diagrams

### What are User Journey Diagrams?

Mermaid's User Journey Diagrams are a visual representation of the steps users take to complete a task within a system, application, or website. These diagrams illustrate the current ("as-is") user workflow, helping identify bottlenecks and areas for improvement in the future ("to-be") workflow.

Mermaid provides the ability to render **User Journey Diagrams** using simple text-based syntax. These diagrams are useful for analyzing and improving user experience.

***

### Creating Your First User Journey Diagram

1. From the Code IDE, click **Apps and Agents** in the left-hand panel.
2. Select **Mermaid**. Paradime will automatically start a new Mermaid project.
3. In the terminal, use the arrow keys to select "User Journey Diagrams."
4. A new `UserJourney.mmd` file will be created in your editor with this starter template:

```mermaid
journey
    title My working day
    section Go to work
      Make tea: 5: Me
      Go upstairs: 3: Me
      Do work: 1: Me, Cat
    section Go home
      Go downstairs: 5: Me
      Sit down: 5: Me
```

<figure><img src="https://2337193041-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FHET0AD04uHMgdeLAjptq%2Fuploads%2F608WEGQbNSqLxIlfHlhM%2Fimage.png?alt=media&#x26;token=b14eb044-4f42-40b1-a9c1-e1794b7fb549" alt=""><figcaption></figcaption></figure>

5. Click the eye icon (👁️) in the top-right corner of your Mermaid file to preview the diagram.
6. Edit and update your `.mmd` file as needed—the preview will update automatically.

***

### Diagram Syntax Guide

#### Basic Structure

A User Journey Diagram consists of the following components:

* **Title**: Describes the overall user journey.
* **Sections**: Break down the journey into major steps or phases.
* **Tasks**: Individual actions within a section.

The basic syntax is as follows:

```mermaid
journey
    title Journey Title
    section Section Title
      Task Name: Score: Actor(s)
```

#### Defining Tasks

Each task is defined with:

* **Task Name**: A descriptive label for the task.
* **Score**: A number from 1 (negative experience) to 5 (positive experience).
* **Actors**: The individuals or entities involved in the task, separated by commas.

Example:

```mermaid
journey
    title Example User Journey
    section Example Section
      Task 1: 4: User
      Task 2: 2: User, System
```

#### Defining Sections

Sections group related tasks together and are defined using the `section` keyword followed by the section title.

Example:

```mermaid
journey
    title Product Purchase Journey
    section Browsing
      View product: 5: User
      Search for alternatives: 4: User
    section Purchase
      Add to cart: 5: User
      Complete payment: 3: User, Payment Gateway
```

***

### Examples

#### E-Commerce Purchase Journey

```mermaid
journey
    title E-Commerce Purchase Journey
    section Browsing
      Explore homepage: 4: User
      Search for products: 3: User
      View product details: 5: User
    section Checkout
      Add to cart: 5: User
      Apply coupon: 3: User
      Make payment: 4: User, Payment Gateway
    section Post-Purchase
      Receive confirmation: 5: User
      Provide feedback: 4: User
```

#### Software Installation Journey

```mermaid
journey
    title Software Installation Journey
    section Download
      Visit website: 4: User
      Select download link: 5: User
    section Installation
      Open installer: 3: User
      Complete setup: 4: User, Installer
    section First Use
      Launch software: 5: User
      Complete onboarding: 3: User, Support Bot
```

***

### Best Practices

1. **Keep it Simple**: Use clear task names and group related tasks into sections.
2. **Use Scores Effectively**: Assign scores based on user experience (1 = poor, 5 = excellent).
3. **Include Relevant Actors**: Specify all participants involved in each task.
4. **Iterate**: Refine the diagram as new insights are gained about the user journey.
5. **Focus on the User**: Highlight pain points and positive moments in the journey.

***

{% hint style="info" %}
### Additional Resources

For more syntax options and advanced features, visit the [official Mermaid documentation](https://mermaid.js.org/syntax/journey.html).
{% endhint %}

