State machines

The statemachine header (aliases state, fsm) draws states as stadium pills and transitions as labelled arrows between them. A node named start or initial becomes a filled circle; end or final becomes the ringed bullseye UML draws for a final state.

statemachine
start -> Idle
Idle -> Loading : fetch
Loading -> Ready : ok
Loading -> Idle : error
Ready -> end : done

Start and end markers#

The pseudo-states are matched by name. start, begin, and initial all draw the entry dot; end, final, stop, and done all draw the exit marker. Everything else is a normal state.

statemachine
initial -> Connecting
Connecting -> Online : connected
Connecting -> Offline : timeout
Online -> Offline : lost
Offline -> Connecting : retry
Online -> stop : quit

Transitions#

A transition is an edge, and the text after : is its trigger or guard. Several transitions can leave one state, one per line, each with its own label. (A state that transitions to itself is a self-edge, which the canvas does not draw; route the failure through a distinct state instead, as Locked → Alarm does below.)

statemachine
start -> Locked
Locked -> Alarm : 3 wrong PINs
Alarm -> Locked : reset
Locked -> Unlocked : correct PIN
Unlocked -> Locked : lock
Unlocked -> end : shutdown

The lifecycle of a background job, from queued to a terminal state.

statemachine
title: Job lifecycle

start -> Queued
Queued -> Running : worker picks up
Running -> Succeeded : ok
Running -> Failed : error
Failed -> Queued : retry
Failed -> Dead : max retries
Succeeded -> end
Dead -> end

An order state machine with cancellation paths.

statemachine
title: Order status

start -> Pending
Pending -> Paid : payment ok
Pending -> Cancelled : timeout
Paid -> Shipped : dispatch
Paid -> Refunded : cancel
Shipped -> Delivered : received
Delivered -> end
Cancelled -> end
Refunded -> end

Composite states and concurrency#

A group { … } block is a composite state: the states inside it are its substates, and groups nest. Mermaid's state X { } imports straight onto it.

Mermaid also splits a composite with a -- divider, meaning the parts above and below run concurrently. Each side becomes its own nested group inside the composite, so "these run in parallel" survives the import rather than flattening into "these are siblings".

statemachine
title: Keyboard

start -> Active

group Active {
  group Active 1 {
    NumLockOff, NumLockOn
  }
  group Active 2 {
    CapsLockOff, CapsLockOn
  }
}

NumLockOff -> NumLockOn : num lock
CapsLockOff -> CapsLockOn : caps lock