Basic state diagram example
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 --> [*]
}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
| Syntax | What it does |
|---|---|
stateDiagram-v2 | Start a state diagram (v2 renderer recommended). |
[*] --> A | Start state transition; A --> [*] is an end state. |
A --> B : event | Transition with an event label. |
state "Long name" as A | State 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 : text | Attach a note. |
direction LR | Lay out left to right. |
State Diagram examples
Choice point
A choice state branches on a condition.
stateDiagram-v2
[*] --> CheckStock
state check <<choice>>
CheckStock --> check
check --> Reserve : in stock
check --> Backorder : out of stock
Reserve --> [*]
Backorder --> [*]Concurrent regions
A media player tracks playback and volume independently.
stateDiagram-v2
[*] --> Active
state Active {
[*] --> Playing
Playing --> Paused : pause
Paused --> Playing : play
--
[*] --> Unmuted
Unmuted --> Muted : mute
Muted --> Unmuted : unmute
}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.
stateDiagram-v2
[*] --> Draft
state "In review" as rev
Draft --> rev : submit
state gate <<choice>>
rev --> gate
gate --> Live : yes
gate --> Draft : no
Live --> [*]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
- Using a quoted label as the id, as in
[*] --> "In review". That line fails. Writestate "In review" as rev, then point arrows atrev. - Leaving out
[*]at the start, so any state looks like a legal entry. The start dot is the contract. - Two ids for one condition because of a typo,
Reviewandreview, which draws two boxes and a machine that can never meet. - A choice whose outgoing arrows have no labels.
yesandnoare 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.