Skip to content
MermaidViewer

Software diagram

Mermaid state diagram

Mermaid state diagram syntax for states, transitions, choices and forks, using stateDiagram-v2, with working examples.

By MermaidViewer editorsPublished Updated

Basic state diagram example

Basic state diagram example diagram
mermaid
stateDiagram-v2
    [*] --> Draft
    Draft --> Review : submit
    Review --> Draft : request changes
    Review --> Approved : approve
    Approved --> Published : publish
    Published --> Archived : archive
    Archived --> [*]
    state Review {
      [*] --> Pending
      Pending --> InReview : assign reviewer
      InReview --> [*]
    }
Open in the live editor

State diagrams describe how something moves between states in response to events — an order going from pending to shipped, a UI component toggling between loading and error, or a connection reconnecting after a timeout.

Mermaid's stateDiagram-v2 supports start and end states, composite (nested) states, choice points, forks and joins, concurrency and notes, which covers almost every state machine you'll document in practice.

When to use a state diagram

  • Order, ticket and subscription lifecycles
  • Frontend component and form states
  • Protocol and connection state machines
  • Game logic and IoT device modes

State Diagram syntax reference

SyntaxWhat it does
stateDiagram-v2Start a state diagram (v2 renderer recommended).
[*] --> AStart state transition; A --> [*] is an end state.
A --> B : eventTransition with an event label.
state "Long name" as AState with a descriptive name.
state A { ... }Composite (nested) state.
state c <<choice>>Choice pseudo-state for branching.
state f <<fork>> / <<join>>Fork and join for parallel paths.
--Separator for concurrent regions inside a composite state.
note right of A : textAttach a note.
direction LRLay out left to right.

State Diagram examples

Choice point

A choice state branches on a condition.

Choice point diagram
mermaid
stateDiagram-v2
    [*] --> CheckStock
    state check <<choice>>
    CheckStock --> check
    check --> Reserve : in stock
    check --> Backorder : out of stock
    Reserve --> [*]
    Backorder --> [*]
Open in the live editor

Concurrent regions

A media player tracks playback and volume independently.

Concurrent regions diagram
mermaid
stateDiagram-v2
    [*] --> Active
    state Active {
      [*] --> Playing
      Playing --> Paused : pause
      Paused --> Playing : play
      --
      [*] --> Unmuted
      Unmuted --> Muted : mute
      Muted --> Unmuted : unmute
    }
Open in the live editor

Lifecycle is the word to test. A mermaid state diagram is the picture of one thing moving through named conditions, from a start dot to a stop dot, with events on the arrows. A flowchart can fake this for a while. It gets clumsy the moment the same state is entered from two places, which is what lifecycles do.

States, events, and a choice

stateDiagram-v2 is the keyword to open with. [*] --> Draft is the start. Live --> [*] is the end. Everything between is a state id. The words on an arrow are the event, written Draft --> rev : submit. The id should be a short token. The label the reader sees can be longer, with state "In review" as rev.

A <<choice>> is a decision that belongs to the machine. You land on it from a state, and you leave on labeled arrows. It's not a place the object stays. If the object waits for a person, that wait is a real state, and the choice comes after.

Name states for the condition, not the action. "In review" is a condition. "Submit" is the event that enters it. If your boxes are all verbs, you have drawn a flowchart with round corners.

Worked example

A page starts as a draft. The author submits it and it waits in review. A choice then either publishes it or sends it back. Live is the end of this small machine.

Mermaid diagram
mermaid
stateDiagram-v2
    [*] --> Draft
    state "In review" as rev
    Draft --> rev : submit
    state gate <<choice>>
    rev --> gate
    gate --> Live : yes
    gate --> Draft : no
    Live --> [*]
Open in the live editor

The start dot removes the argument about which box is first. rev is the id, and "In review" is the only text on that box, so you can rename the label later without retargeting arrows. The choice has no business meaning of its own. yes publishes, no returns to Draft, and Draft is allowed to run again. That loop is the reason this is a state diagram. A straight flowchart would copy the draft box a second time to show the return.

Live --> [*] says publishing is terminal here. If unpublish is real, add Live --> Draft : unpublish and delete the stop, or keep the stop for the archive path only. Don't leave a stop on a state the object can still leave. Readers treat [*] as gone. Event names should be verbs the product already uses. "submit" and "yes" are thin, and that's fine on a sketch. Replace "yes" with "approve" once the team has a real word for the transition, so the diagram matches the UI.

When this is the wrong diagram

A flowchart is the better fit for a procedure that's not the lifecycle of one object, such as a support policy with several roles. A sequence diagram is the better fit when the interesting part is the messages between author, app, and mailer. Use a state diagram when you can point at one noun and list the conditions it sits in.

Common mistakes

  1. Using a quoted label as the id, as in [*] --> "In review". That line fails. Write state "In review" as rev, then point arrows at rev.
  2. Leaving out [*] at the start, so any state looks like a legal entry. The start dot is the contract.
  3. Two ids for one condition because of a typo, Review and review, which draws two boxes and a machine that can never meet.
  4. A choice whose outgoing arrows have no labels. yes and no are the decision. Without them the diamond is a fork with no policy.

Where to go next

The AI state diagram generator drafts the conditions from a short description. Check the return arrows in the editor, and use the cheat sheet when you forget the start-dot form. The order state machine template is a fuller lifecycle, with payment and cancellation, if you want a second example beside this review flow.

Reading it against the code

A state is a value you can log. If the enum in the source has pending, paid, and failed, those three words are the states, spelled the same way. A transition that the code cannot take, such as failed --> paid with no retry function, does not belong on the chart just because the meeting wished it did. Add the arrow when the function exists.

Tips and best practices

  • Name states with nouns or adjectives (Pending, Active) and transitions with verbs or events (submit, timeout).
  • Use composite states to hide detail; readers can zoom into a nested state only when they need to.
  • Use stateDiagram-v2 rather than stateDiagram for better layout and styling support.

Generate a state diagram with AI

Not sure where to start? Describe what you need and the AI state diagram generator writes the Mermaid code for you. Try prompts like:

  • “Subscription lifecycle with trial, active, past due and cancelled”
  • “Traffic light controller”
  • “Support ticket workflow”

State Diagram templates

State Diagram FAQ

What is the difference between stateDiagram and stateDiagram-v2?

stateDiagram-v2 uses the newer renderer with better layout, styling and composite-state support. The syntax is the same, so you can usually just add -v2.

How do I draw a start and end state?

Use [*]. [*] --> First marks the initial state and Last --> [*] marks a final state.

Can a state diagram show parallel states?

Yes. Inside a composite state, separate concurrent regions with a line containing only --, or use <<fork>> and <<join>> pseudo-states.