Stable lifecycle states
Name conditions such as Draft, Submitted, and Approved instead of turning every action into a state.
Lifecycle and transition modeling
Mermaid State Diagram Online Editor
Describe the lifecycle of one order, request, or job with Mermaid stateDiagram-v2. Show stable states, events, conditional branches, and completion paths, then review the transitions in the editor above.
Build a Mermaid state diagram online
Adapt the approval and revision lifecycle below. Transition labels explain events or conditions; they do not execute business rules.
Loading diagram preview...
See which transitions a lifecycle permits
Choose a state diagram when the question is what one subject can become next. Use a flowchart when you need to show the steps performed by a process.
Events on transitions
Label changes with submit, approve, timeout, or another event that explains why the subject moves.
Choices and completion
Show alternative outcomes with a choice and explicit initial or terminal markers.
Composite states
Group a phase with its own internal lifecycle when one level of states no longer explains the behavior.
Map the lifecycle of one subject
Keep a single subject throughout the diagram so transitions have a consistent meaning.
- 01
Declare stateDiagram-v2 and list stable states. Connect [*] to the first state.
- 02
Add transitions with event labels, a choice for conditional outcomes, and a terminal marker where completion is intended.
- 03
Manually follow normal, rejected, and recovery paths in the preview. Check whether every state can be reached before exporting.
State syntax for entry, choices, and nested lifecycles
Mermaid draws the transitions and labels you write. It does not execute guards or decide whether the modeled business rules are valid.
Mermaid state diagram syntax reference →Initial and terminal markers
Use [*] as a transition source for entry and as a target for completion. Check that terminal outcomes really end the lifecycle.
stateDiagram-v2
[*] --> Draft
Draft --> Submitted : submit
Submitted --> Approved : approve
Approved --> [*]Readable state names and event labels
Use a short ID with a display name if a label needs spaces. A colon introduces display text on a transition.
stateDiagram-v2
state "Awaiting payment" as Awaiting
Awaiting --> Paid : payment received
Awaiting --> Cancelled : timeoutA choice with conditional outcomes
Declare <<choice>> and label its outgoing paths. The conditions are explanatory text, not expressions checked by the editor.
stateDiagram-v2
state Review <<choice>>
Submitted --> Review
Review --> Approved : valid
Review --> Rejected : invalidA composite state
A state block contains its own lifecycle. Mermaid does not support transitions between internal states belonging to different composite states.
stateDiagram-v2
[*] --> Processing
state Processing {
[*] --> Validating
Validating --> Ready : valid
Ready --> [*]
}
Processing --> Complete
Complete --> [*]Mermaid state diagram example
A draft is submitted for review. Valid requests reach approval and completion; rejected requests return to Draft for revision.
stateDiagram-v2
[*] --> Draft
Draft --> Submitted : submit
Submitted --> Review
state Review <<choice>>
Review --> Approved : valid
Review --> Rejected : invalid
Approved --> [*]
Rejected --> Draft : revise- submit and revise describe events on transitions, while Draft and Submitted describe stable conditions.
- Review is a choice node. Its valid and invalid labels need to match rules in your application.
- Try adding a cancellation event from Draft and Submitted, then decide whether Cancelled should terminate the lifecycle.
Frequently asked questions
Does [*] mean start or finish?
It depends on its position: [*] --> Draft introduces the initial state, while Approved --> [*] represents a terminal outcome.
How do I add a condition to a transition?
Add a colon followed by readable condition text, such as Review --> Approved : valid. This is a label; Mermaid does not execute or validate it.
How do I show a decision point?
Declare a state with <<choice>> and connect it to each possible outcome with a clear condition label.
How do I show cancellation or a retry?
Add event-labeled transitions such as Draft --> Cancelled : cancel and Rejected --> Draft : revise. Connect Cancelled to [*] only if cancellation ends the lifecycle, and trace both paths manually.
Can I connect internal states in different composite states?
Mermaid does not support that cross-composite transition pattern. Keep the interaction at the composite-state boundary or restructure the model.
When should I use a flowchart instead?
Use a flowchart for actions and decisions in a process. Use a state diagram for the allowed transitions of one subject, such as an order or background job.
Compare state modeling
Mermaid vs PlantUML state diagrams
Compare syntax, nested states, lifecycle notation, and the modeling depth available in each text-based diagram tool.
Read the state diagram comparison →