4.2 State Diagrams

1. Explain state machines.

2. stateDiagram keyword.

3. States, transitions, start/end.

---

1. Explain State Machines

So far, you’ve learned how to use Mermaid for flowcharts, sequence diagrams, and class diagrams, which help you map out steps, interactions, and structure. But what if you need to show how something changes over time, or how it behaves based on its current state? That’s where state machines — and state diagrams — come in.

---

✅ What is a State Machine?

A state machine (or finite state machine, FSM) is a way to describe how a system or object can:

• Exist in one state at a time

• Transition from one state to another

• React to events or actions that trigger those changes

A state machine is like a map of all possible conditions an object can be in, plus the rules for moving between them.

---

✅ Why Use State Machines?

State machines are used when:

• A system has clearly defined statuses.

• The system’s behavior changes depending on its current state.

• Certain actions are only valid in specific states.

They’re common in:

• UI design (button states: idle → hovered → clicked → disabled)

• Authentication flows (logged out → logging in → logged in → session expired)

• IoT devices (on → standby → off)

• Game development (player states: idle → running → jumping)

---

✅ Key Concepts

State: A condition your system can be in. Example: Draft, Published, Archived.

Transition: A rule or trigger that moves the system from one state to another. Example: Submit for review, Approve, Reject.

Event: The thing that causes the transition — like a user action or system event.

Start and End States: State machines usually have a defined starting state and, optionally, an end state to show where the process finishes.

---

✅ How State Machines Help

State machines help you:

• Prevent invalid states (How did this get approved without being reviewed?)

• Design clear rules (A task can’t go from Archived back to Draft.)

• Communicate expected behavior to developers, testers, or stakeholders.

They reduce bugs, because everyone can see exactly which states exist and what transitions are allowed.

---

✅ Example in Real Life

Think of a traffic light:

• States: Green, Yellow, Red.

• Transitions: Timer expires → Next state.

• The light can only be in one state at a time, and the transition rules define how it cycles safely.

---

In short:

📌 A state machine is a simple but powerful way to describe how a system moves between conditions — and state diagrams help you visualize those changes clearly, step by step.

---

2. stateDiagram Keyword

Now that you understand what a state machine is and why it’s useful, let’s see how to draw one in Mermaid. Mermaid makes this easy with the stateDiagram keyword. When you start a diagram with stateDiagram, you tell Mermaid: “Render this as a state machine diagram, showing states and transitions.”

---

✅ How to Start a State Diagram

A state diagram always begins with:

stateDiagram

Below that, you define:

• States (the different conditions your system can be in)

• Transitions (arrows that connect states)

• Start and End states (optional, but helpful for showing where the process begins and finishes)

---

✅ Basic Syntax

The simplest syntax looks like this:

stateDiagram
  [*] --> State1
  State1 --> State2
  State2 --> [*]

• [ * ] represents the start or end state.

• --> defines a transition from one state to another.

---

✅ Example: Simple Workflow

Here’s a simple state diagram for a document:

```mermaid
stateDiagram
  [*] --> Draft
  Draft --> Review
  Review --> Approved
  Approved --> [*]
```

How this works:

• The document starts in the Draft state.

• It moves to Review when submitted.

• If approved, it transitions to Approved.

• [ * ] at the end shows the process is finished.

---

✅ Adding Labels

You can label transitions to explain what triggers a state change:

stateDiagram
  [*] --> Draft
  Draft --> Review: Submit
  Review --> Approved: Approve
  Review --> Draft: Reject
  Approved --> [*]

Here:

• The transition from Draft to Review happens when someone Submits.

• From Review to Approved if someone Approves.

• Or back to Draft if Rejected.

---

✅ Nested States

State diagrams can also have nested states for more complex flows:

stateDiagram
  [*] --> Order_Placed
  Order_Placed --> Shipped
  Shipped --> Delivered

  state Shipped {
    [*] --> In_Transit
    In_Transit --> Out_for_Delivery
    Out_for_Delivery --> Delivered
  }

This shows:

• Shipped is a composite state with its own inner states: In Transit → Out for Delivery → Delivered.

---

✅ When to Use stateDiagram

Use stateDiagram when you want to:

• Show how an item or system changes over time.

• Make valid states and transitions obvious.

• Prevent confusion about invalid jumps (e.g., skipping steps).

---

In short:

📌 The stateDiagram keyword is your starting point for mapping out conditions, events, and flows — helping you explain exactly how something moves from state to state.

---

3. States, Transitions, Start/End

When building a state diagram with Mermaid, three elements work together to describe how something moves and changes over time: states, transitions, and start/end points. Let’s break each part down step by step.

---

✅ 1️⃣ States

A state represents a specific condition your system, object, or process can be in at any moment. Each state has:

• A name (like Draft, Review, or Approved)

• A unique meaning — only one state is “active” at a time in a simple finite state machine.

In Mermaid, you define states by simply writing their names:

Draft
Review
Approved

States don’t need brackets or extra symbols — they’re just named steps in your process.

---

✅ 2️⃣ Transitions

A transition is the path your system takes to move from one state to another. Transitions are shown with arrows: -->.

You can:

• Use --> to draw the arrow.

• Add a label to explain what event triggers the change.

Example:

Draft --> Review: Submit
Review --> Approved: Approve
Review --> Draft: Reject

This means:

• The Draft goes to Review when you Submit.

• Review goes to Approved if you Approve.

• Or Review goes back to Draft if you Reject.

---

✅ 3️⃣ Start and End States

Every good state diagram should show:

• Where the process begins (the start state)

• Where it finishes (the end state)

Mermaid uses [ * ] (asterisk in brackets) to show both:

• [ * ] --> StateName means start here.

• StateName --> [ * ] means end here.

Example:

[*] --> Draft
Approved --> [*]

This means:

• The process starts in Draft.

• When it reaches Approved, it’s done.

---

✅ Putting It All Together

Here’s a complete example combining all three:

```mermaid
stateDiagram
  [*] --> Draft
  Draft --> Review: Submit
  Review --> Approved: Approve
  Review --> Draft: Reject
  Approved --> [*]
```

How it works:

• The workflow starts in Draft.

• It can move to Review when submitted.

• From Review:

  • If approved, it finishes in Approved.

  • If rejected, it loops back to Draft.

• The [ * ] at the end shows the final end state.

---

✅ Why It Matters

• States show what your thing can be.

• Transitions show how it moves or changes.

• Start and end points keep your diagram clear and realistic — everyone can see where it begins and what counts as “done.”

This makes state diagrams great for modeling:

• Content workflows (Draft → Review → Published)

• Login states (Logged Out → Logging In → Logged In)

• Device modes (Off → Standby → On)

---

In short:

📌 States define where you are. 📌 Transitions define how you get there. 📌 Start and end states show where the story begins and ends — giving you a clean, easy-to-follow map of how things change over time.

---