# State Machine Diagram

**In short:** A state machine diagram shows the states an object or behavior can be in. It also shows the events that move it between states, and what happens on each move.

## Explanation

A state machine diagram draws the life of something as **states** and **transitions**. A state is a situation the thing can be in. A transition is a move from one state to another.

**Where it starts and ends**

- The initial transition starts at a solid circle. It points to the default state.
- A region can have at most one initial vertex, meaning one starting point.
- Entering a final state means the enclosing region has completed.
- Entering a terminate pseudostate stops the whole state machine at once.

**Transition labels**

A transition label can carry a guard and an effect. The guard is a condition in square brackets. The effect comes after a slash. See State Machine Transition and Transition Syntax (Trigger, Guard, Behavior).

A completion transition has an implicit trigger, so it needs no written event. A time event occurs at a specific point in time.

**Behavior inside a state**

A state may have an entry behavior, a do behavior and an exit behavior. The entry action runs when the state is entered. The exit action runs whenever the state is left. The do action repeats as long as the state does not change. See State Entry, Exit and Do Behavior.

**Branching**

- A junction joins several transitions into compound paths.
- A choice is a dynamic conditional branch. If no guard on its outgoing transitions is true, the model is ill formed.

**Nesting and reuse**

- Composite states contain other states. They can hold several regions that model parallel behavior. See Composite State and Concurrent Region.
- When a composite state is left, exit starts at the innermost active state.
- A submachine state lets you reuse one state machine specification many times. Its connection points match entry and exit points in the referenced machine.

## Example

Picture a simple online order. It starts in *Created*. A payment event moves it to *Paid*, but only if the amount is correct (the guard). The effect sends a receipt. From *Paid*, a shipping event moves it to *Shipped*, and then it reaches a final state. The same event, such as "cancel", could be handled differently in each state.

## Trade-offs

Nesting, parallel regions and reusable submachines let you structure large behavior. They also make the diagram harder to read, because exit and entry actions run across state boundaries. A choice whose guards do not cover every case makes the model ill formed. Check that at least one guard is always true.

A small state machine: initial transition, a transition with guard and effect, and a final state.

```plantuml
@startuml
[*] --> Created
Created --> Paid : payment [amount correct] / send receipt
Paid --> Shipped : ship
Shipped --> [*]
@enduml
```

## Checks

- Each region has at most one initial vertex.
- Every choice pseudostate has outgoing guards that cover all cases, so at least one is true.
- Transition labels write the guard in square brackets and the effect after a slash.
- Any use of a terminate pseudostate is intentional, since it stops the whole state machine immediately.

## Related

- [State Machine Transition](https://arc.fuet.ch/concepts/modeling-uml/state-machine-transition.md)
- [Transition Syntax (Trigger, Guard, Behavior)](https://arc.fuet.ch/concepts/modeling-uml/transition-syntax.md)
- [State Entry, Exit and Do Behavior](https://arc.fuet.ch/concepts/modeling-uml/state-entry-exit-and-do-behavior.md)
- [Composite State](https://arc.fuet.ch/concepts/modeling-uml/composite-state.md)
- [Concurrent Region](https://arc.fuet.ch/concepts/modeling-uml/concurrent-region.md)
- [State and Event](https://arc.fuet.ch/concepts/modeling-uml/state-and-event.md)
- [State Machine Diagram Modeling Mistakes](https://arc.fuet.ch/concepts/modeling-uml/state-machine-diagram-modeling-mistakes.md)
- [UML Behavioral Diagram](https://arc.fuet.ch/concepts/modeling-uml/behavior-diagram.md)

## Sources

- [UML state machine - Wikipedia](https://en.wikipedia.org/wiki/UML_state_machine) — en.wikipedia.org, accessed 2026-11-09
- [Unified Modeling Language 2.5.1 | Webel IT Australia](https://www.webel.com.au/node/424) — webel.com.au, accessed 2026-11-09
- [UML State Diagram: Sequence of states](https://www.sparxsystems.eu/languages/uml/diagrams/statediagram/) — sparxsystems.eu, accessed 2026-11-09