5.1.1 What Is a State Diagram?
A state diagram (also called a state machine diagram) models how a system transitions between different states over time.
Unlike:
Flowcharts → model process steps
Sequence diagrams → model interactions
Class diagrams → model structure
State diagrams model:
Events triggering transitions
State diagrams are ideal for:
In Mermaid, every state diagram begins with:
Mermaid uses stateDiagram-v2 for modern syntax support.
5.1.2 Basic State Definition
The simplest state diagram:
Explanation:
[ * ] represents the start or end node
Idle and Processing are states
--> represents transitions
The diagram reads:
Start → Idle → Processing → End
5.1.3 Understanding Start and End States
Special notation:
Example:
This models login lifecycle.
5.1.4 Named States
States are defined simply by referencing them.
Mermaid automatically creates states when referenced.
You do not need explicit declaration unless styling or grouping is required.
5.1.5 Adding Labels to Transitions
Transitions can include event names.
Syntax:
Example:
This represents a document approval workflow.
5.1.6 Self-Transitions
A state can transition to itself.
Full example:
Useful for:
5.1.7 Composite (Nested) States
States can contain substates.
Syntax:
Example:
This models:
Internal lifecycle stages
Composite states are powerful for complex systems.
5.1.8 Choice States (Decision Nodes)
Choice nodes represent conditional branching.
Syntax:
Example:
Choice nodes resemble decision diamonds in flowcharts but apply to state logic.
5.1.9 Real-World Example — Payment Lifecycle
This models a real payment processing lifecycle.
State diagrams are particularly strong for lifecycle modeling.
5.1.10 Guard Conditions (Conceptual)
Mermaid allows event labeling, but guard conditions are typically represented inside the label.
Example:
This indicates conditional transition.
Though Mermaid does not enforce formal guard syntax like full UML, event labeling communicates conditions clearly.
5.1.11 Parallel States (Advanced Preview)
Mermaid supports parallel states using -- separators.
Example:
This models:
Payment and Shipping progressing independently
Parallel modeling is useful for distributed workflows.
5.1.12 Minimal Valid State Diagram
That is all that is required for a valid state diagram.
5.1.13 Common Beginner Mistakes
Forgetting stateDiagram-v2
Using flowchart syntax inside state diagrams
Confusing state transitions with message flows
Overcomplicating simple workflows
Incorrect:
Correct:
5.1.14 Refactoring Example (Hands-On)
Start simple:
Now refine with events and lifecycle clarity:
This models a realistic account lifecycle.
5.1.15 Hands-On Exercise
Design a Ticketing System Lifecycle:
States:
Requirements:
Add at least one self-transition
Include one composite state
Focus on lifecycle correctness.
5.1.16 Best Practices
Use state diagrams for lifecycle modeling only
Keep transitions event-driven
Avoid modeling algorithm steps
Use composite states for complexity
Remember:
State diagrams represent how an entity evolves over time, not how processes execute step-by-step.
5.1.17 Key Takeaways
State diagram syntax includes:
stateDiagram-v2 declaration
State diagrams are powerful for modeling:
In the next topic, we will explore Transitions and Composite States in greater depth, including advanced modeling patterns and structuring complex state machines.
