How to Create a State Machine Diagram

By the Diagramium team · 2026-08-13 · 6 min read

To create a state machine diagram, list every distinct condition one thing can be in, draw each as a rounded box, then connect them with arrows labelled by whatever causes the move. Add an initial state marking where life begins and at least one terminal state marking where it ends, and the diagram is complete enough to check against.

Live interactive diagramUse the player controls to follow the steps

The life of a stock trade orderPlaying silently in this guideWatch with narration Open in editor

This compact player stays quiet while you read. Open the full presentation when you want narration and the complete walkthrough.

When a state machine diagram is the right choice

A state machine describes one thing's lifecycle. Not a process with several actors, not a sequence of messages — one object, and the conditions it can be in over its life. The tell is that you can say "it is currently…" and finish the sentence with a single word: pending, active, revoked.

It earns its place when the states are contested or the illegal transitions matter:

An order, a subscription, a certificate. Anything with a status column in a database is a state machine whether or not anyone drew it, and the undrawn ones are where the bugs live.
Anything with a terminal state. Once revoked, a certificate cannot become valid. A diagram makes that irreversibility visible; prose tends to omit it.

If you cannot finish the sentence "it is currently…" with one word, you are not looking at a state.

States, transitions, guards and terminals

State. A rounded box, named as an adjective or past participle — Pending, Shipped, Cancelled. Never a verb: Shipping is an activity, Shipped is a state.
Transition. An arrow from one state to another, labelled with its trigger — the event that causes the move.
Guard. A condition on a transition, conventionally in square brackets: payment received [funds cleared]. It means the trigger alone is not enough.
Initial state. A filled circle with an arrow into the first real state. Every machine has exactly one.
Terminal state. A ringed circle. A machine may have several, or none if the lifecycle genuinely loops forever.
Self-transition. An arrow leaving and re-entering one state — a retry, a renewal, an edit that does not change status.

The state machine editor carries the full UML pseudostate set beyond these — choice, junction, history, fork and join — for the cases that need them. Most working diagrams need only the six above.

How to create a state machine diagram, step by step

Name the thing. One noun: an order, a key, a subscriber. If you are tempted to say "the order and the payment", that is two machines.
List the states. Every value the status can hold. Reading the actual enum or status column is the fastest honest way to start.
Mark where it begins. The initial state, with its arrow in.
Mark where it ends. Terminal states, and be explicit about which are irreversible.
Draw the transitions people expect. The happy path first: created → paid → shipped → delivered.
Label each with its trigger. What event causes it. An unlabelled transition is an assertion that it happens by itself.
Add guards where the trigger is not sufficient. This is where real business rules surface.
Hunt the missing arrows. For each state ask: what else could happen here? Timeouts, cancellations and failures are the transitions everyone forgets, and they are usually the ones that break in production.

Worked examples you can open and edit

State machineThe life of a stock trade orderA trade order: validated, routed, resting, filled or cancelled — states with real money attached.View example Use template
State machineThe life of a certificateIssued, renewed, expired, revoked — and why revoked is terminal but expired is not.View example Use template
State machineFeature flag lifecycleDark launch through percentage rollout to removal, gated on metrics.View example Use template
State machineSubscription-box lifecycleActive, paused, past due, cancelled — the involuntary transitions are the interesting ones.View example Use template
State machineNarratedWatch onlyGit: where your changes actually liveEvery state a file passes through in Git, including the ones people forget.View example Play presentation
State machineNarratedWatch onlySolid, liquid, gas: states of matterFour states, every transition named — the clearest small example of the notation.View example Play presentation

States with money attached

The trade-order lifecycle is worth studying because it has states people do not think of as states. An order is not just open or filled — it is validated, routed, resting in the book, partially filled, then filled or cancelled. Partially filled is the one that catches teams out: it is a real, durable state with its own legal transitions, and a system that models it as "not filled yet" gets the accounting wrong.

Terminal states that mean different things

The certificate lifecycle makes a distinction the notation is unusually good at showing. Expired and revoked are both end states, but expired is a natural end that renewal anticipates, while revoked is a deliberate, irreversible kill. Two terminal states, reached by different triggers, with no arrow between them — the picture says in one glance what a paragraph struggles to make unambiguous.

Building one in Diagramium

Open the state machine editor.

Drop states from the shapes panel, along with initial and terminal markers.
Drag from a port to another state to create a transition.
Label transitions with trigger and guard in the inspector.
Self-transitions loop from a state back to itself for retries and renewals.
Press Present to walk the lifecycle one state at a time — the natural way to review whether a transition is missing.

The state machine editor is canvas-only; the Text editor tab is hidden in this mode rather than offering syntax that does not apply.

Present reveals the machine state by state, which is exactly how a lifecycle review should run — you want people to challenge each transition as it appears.
Export PNG, SVG or PDF free without an account. Animated SVG, GIF and video need a free account, not a subscription.
Embed a published diagram next to the code that implements it.

Common mistakes

Verbs as state names. Processing payment is an activity. The state is Awaiting payment or Paid.
No terminal state. Almost everything ends. If yours genuinely does not, say so deliberately rather than by omission.
Unlabelled transitions. Without a trigger, the diagram claims the change happens spontaneously.
Missing failure paths. Timeouts, cancellations, payment failures. Walk each state and ask what else could happen — that pass finds more bugs than the happy path ever will.
Modelling two things at once. An order's states and a shipment's states are two machines that reference each other, not one machine.
A transition out of a terminal state. If something leaves it, it was never terminal — and that is worth catching before it is code.

Several participants exchanging messages in order: sequence diagram.
A procedure with decisions rather than an object's lifecycle: flowchart.
The same process split by who owns each step: swimlane diagram.
The data the object is stored as: ER diagram.
The classes behind it, including behaviour: UML class diagram.

Questions people actually ask

What is the difference between a state machine diagram and a flowchart?

A flowchart shows a procedure — the order of actions and decisions. A state machine shows the conditions one object can be in and what moves it between them. A flowchart's boxes are things you do; a state machine's boxes are things you are.

What is a guard condition?

A condition attached to a transition, written in square brackets, meaning the trigger fires only when it holds — renewal requested [not revoked]. It is where business rules become explicit.

Does every state machine need a terminal state?

Most do. Some genuinely cycle forever — the accounting cycle, a moon phase — and those correctly have none. Make it a decision rather than an oversight.

How do I know I have found all the states?

Read the status field in the database or the enum in the code. Then ask, for each state, what a timeout or a cancellation would do — those two questions surface most of the states that were never written down.

Can a state have a transition to itself?

Yes, and it is common: a retry, a renewal, or an edit that changes data without changing status.

Ready to build one? Open the State machine editor on a blank canvas, or start from one of the templates above — they are all editable.Open the State machine editor Browse all templates