UML state diagram notation reference
A UML state machine diagram uses a small vocabulary of precisely defined symbols. Each element has a specific meaning that readers familiar with UML will interpret unambiguously.
| Element | Symbol | Meaning |
|---|---|---|
| Initial pseudostate | ● (filled black circle) | The starting point of the state machine. Every state diagram has exactly one. A transition from the initial pseudostate leads to the first active state. |
| State | Rounded rectangle with state name | A stable condition the object occupies. May include compartments for entry, exit, and do-activities written inside the box. |
| Final state | ◎ (circle inside a circle) | Marks the end of the state machine lifecycle. An object that reaches the final state has completed its modelled behaviour. |
| Transition | Directed arrow between states | A response to an event that moves the object from source state to target state. Label syntax: trigger [guard] / action. |
| Guard condition | [boolean expression] on a transition | An optional condition in square brackets that must evaluate to true for the transition to fire. Allows one trigger to route to different target states based on data. |
| Entry / exit action | entry / action or exit / action inside state | Behaviour that runs automatically every time the state is entered or exited, regardless of which transition triggered the change. |
| Choice pseudostate | ◇ (diamond) | A decision point where guards on outgoing transitions select the next state. Exactly one outgoing guard must be true; one is conventionally marked [else]. |
Real-world example: order lifecycle states
An e-commerce order moves through a predictable set of states from creation to completion. The following table shows the transitions, their triggers, and the guard conditions that control them.
| From state | To state | Trigger | Guard / Action |
|---|---|---|---|
| ● (initial) | Pending | orderPlaced | — / assign order ID, send confirmation email |
| Pending | Processing | paymentConfirmed | [payment.status == 'success'] / reserve inventory |
| Pending | Cancelled | paymentConfirmed | [payment.status == 'failed'] / release hold, notify customer |
| Processing | Shipped | fulfilmentComplete | — / send tracking number |
| Shipped | Delivered | deliveryConfirmed | — / close order, trigger review request |
| Shipped | Cancelled | returnRequested | [withinReturnWindow] / initiate return label |
| Delivered | ◎ (final) | — | — (terminal state) |
| Cancelled | ◎ (final) | — | — (terminal state) |
Type this prompt into flow-chart.io to generate the above state diagram:
Order lifecycle state diagram: An order starts Pending after placement. It moves to Processing when payment is confirmed [payment.status == 'success'], with entry action to reserve inventory. It moves to Cancelled when payment fails. From Processing it moves to Shipped when fulfilment is complete, with action to send a tracking number. From Shipped it moves to Delivered when delivery is confirmed, or to Cancelled if a return is requested [withinReturnWindow]. Both Delivered and Cancelled are terminal states. Show as a UML state machine diagram.
Real-world example: user authentication states
An authentication session passes through a well-defined set of states from initial page load to token expiry. This diagram is useful for documenting session management in web applications.
| From state | To state | Trigger | Guard / Action |
|---|---|---|---|
| ● (initial) | Unauthenticated | appLoaded | — / check stored token |
| Unauthenticated | Authenticating | loginSubmitted | — / send credentials to auth service |
| Authenticating | Authenticated | authSuccess | — / store JWT, start session timer |
| Authenticating | Unauthenticated | authFailure | [attempts < 5] / show error message |
| Authenticating | Locked | authFailure | [attempts >= 5] / lock account, notify security team |
| Authenticated | SessionExpired | sessionTimerElapsed | — / clear token, show expiry notice |
| Authenticated | Unauthenticated | logoutRequested | — / clear token and session |
| SessionExpired | Authenticating | loginSubmitted | — / re-authenticate |
| SessionExpired | Unauthenticated | dismissed | — |
Real-world example: traffic light controller
A traffic light is a classic state machine with cyclic transitions and no terminal state. It demonstrates timed triggers and the use of entry actions for output control.
| State | Entry action | Trigger | Next state |
|---|---|---|---|
| Red | entry / showRed, startTimer(60s) | timerElapsed | Green |
| Green | entry / showGreen, startTimer(45s) | timerElapsed | Yellow |
| Yellow | entry / showYellow, startTimer(5s) | timerElapsed | Red |
Composite states and nested state machines
A composite state contains a nested sub-state machine drawn inside its boundary. All sub-states inherit transitions defined on the composite state, which eliminates repetition across sibling states.
For example, consider an 'Authenticated' composite state containing sub-states 'Browsing', 'Checkout', and 'OrderReview'. Rather than adding a sessionTimeout transition to each sub-state individually, a single transition on the 'Authenticated' composite state routes all three sub-states to 'SessionExpired' when the session timer elapses.
Orthogonal composite states use dashed dividing lines to create concurrent regions. Each region runs its own sub-state machine independently. This models objects that track multiple simultaneous concerns — for example, a media player that tracks playback state (Playing / Paused / Stopped) independently from volume state (Normal / Muted) in parallel regions.
When generating composite states in flow-chart.io, describe the grouping in plain language: "Group Browsing, Checkout, and OrderReview inside an Authenticated composite state. The Authenticated state transitions to SessionExpired on sessionTimerElapsed from any sub-state."
State diagram best practices
- Keep the number of states to 12 or fewer per diagram. Use composite states to group related sub-states rather than expanding one flat diagram.
- Name states with a noun or adjective describing the object's condition — 'Authenticated', 'Locked', 'Processing' — not the action that caused the transition.
- Label every transition with at least a trigger event. Add a guard only when one trigger can lead to multiple target states depending on data.
- Verify every state is reachable from the initial pseudostate and every non-final state has at least one outgoing transition.
- Use entry actions for initialisation (starting timers, loading data) and exit actions for cleanup (stopping timers, releasing locks).
- Add a choice pseudostate (diamond) when a transition's target depends on evaluated conditions — this makes branching logic explicit and readable.
- Trace at least one happy path and one error path through the complete diagram to validate that all states and transitions are covered before sharing the diagram.
How AI state diagram generation works in flow-chart.io
- Intent detection. The prompt is parsed to identify states, events, guards, and actions. Phrases like "moves to X when Y happens" map to transitions; "only if Z" maps to guards; "on entering, do A" maps to entry actions.
- Typed generation. Each element is a typed scene-graph object — not a freehand shape. States are rounded rectangle nodes; transitions are directed edge objects with trigger, guard, and action fields; pseudostates are specialised nodes. Every element conforms to UML 2.5.1 notation.
- Layout pass. States are arranged to minimise crossing transitions. The initial pseudostate is positioned at the top-left; the flow proceeds left-to-right and top-to-bottom. Composite states are rendered with their sub-states inside a larger boundary rectangle.
Because the output is a typed scene graph, every element is immediately editable — double-click a state to rename it, drag a transition endpoint to rewire it, or add a new state from the toolbar.