State diagram

About state diagrams

A state diagram (also called a statechart or state machine diagram) describes the lifecycle of a reactive system — what states it can be in, what events cause it to move between them, and what actions run on entry, exit, or during a state. Software architects use them to specify workflows; controls engineers use them to design reactive controllers; UI designers use them to model screen lifecycles. They are formalized in OMG UML 2.5.1 §14 (state machines) and Harel's 1987 Statechart extension that introduced composite states, history, and orthogonal regions.

Schematex implements a strict superset of Mermaid stateDiagram-v2 — every Mermaid example pastes in unchanged, plus you get UML 2.5 features Mermaid doesn't expose: entry / exit / do activities, full trigger [guard] / action transition labels, terminate and history pseudo-states, junction, and Schematex-style block notes. Layout uses the same Sugiyama-layered-DAG engine as flowcharts, so cycles, composite states, and cross-boundary transitions all route cleanly.

Cannot detect diagram type. Start your text with 'genogram', 'ecomap', 'pedigree', 'phylo', 'sociogram', 'timing', 'logic', 'circuit', 'blockdiagram', 'ladder', 'sld', 'entity-structure', 'fishbone', 'venn', 'flowchart', 'mindmap', 'matrix', or 'orgchart'.

1. Your first state diagram

The smallest useful state diagram has an initial state, a final state, and one transition.

Cannot detect diagram type. Start your text with 'genogram', 'ecomap', 'pedigree', 'phylo', 'sociogram', 'timing', 'logic', 'circuit', 'blockdiagram', 'ladder', 'sld', 'entity-structure', 'fishbone', 'venn', 'flowchart', 'mindmap', 'matrix', or 'orgchart'.

Three rules cover 80% of usage:

1. Start with stateDiagram-v2 (Mermaid-style) or state (Schematex-style) header.
2. Use [*] for the implicit start node (when on the left of -->) or end node (when on the right).
3. Connect states with -->. Add a label after : — full UML form is trigger [guard] / action.

The default direction is TB (top-to-bottom) to match Mermaid. Override with direction LR on its own line, or [direction: LR] on the header.

Comments use %% (Mermaid), #, or //.

2. State declarations

States are auto-created when first referenced in a transition, but explicit declarations let you control the label and shape.

state Authenticating
state "Awaiting Approval" as Approval
Idle: Waiting for input

3. Pseudo-states

Pseudo-states control the flow of a state machine without representing a stable resting state.

[*] is the Mermaid alias and is always direction-resolved: on the source side of --> it's an initial, on the target side it's a final. Each composite scope gets its own pair.

Cannot detect diagram type. Start your text with 'genogram', 'ecomap', 'pedigree', 'phylo', 'sociogram', 'timing', 'logic', 'circuit', 'blockdiagram', 'ladder', 'sld', 'entity-structure', 'fishbone', 'venn', 'flowchart', 'mindmap', 'matrix', or 'orgchart'.

4. Transitions

The full UML 2.5 transition label has three optional parts:

trigger [guard] / action

All three are optional — an unlabeled transition is anonymous (completion transition).

A --> B                                      %% anonymous completion
A --> B : tick                                %% trigger only
A --> B : [count > 0]                         %% guard only
A --> B : / clearErrors()                     %% action only
A --> B : tick [count > 0] / log()            %% all three
A --> B : tick, tock [enabled] / handle()     %% multi-trigger

Long labels wrap automatically when they exceed the lane width.

5. Composite states

A composite state contains a nested sub-statechart. The outer state acts as a container with its own initial / final pseudo-states.

state Playing {
  [*] --> Buffering
  Buffering --> Streaming : buffer_full
  Streaming --> Buffering : underflow
}

Both Mermaid syntax (state X { … }) and the Schematex form (composite X { … }) are accepted. Activities can be declared inside the composite block:

state Playing {
  entry / startBuffer()
  exit / stopBuffer()
  do / decodeFrames()

  [*] --> Buffering
  Buffering --> Streaming : buffer_full
  Streaming --> Buffering : underflow
}

The renderer draws composites as a styled cluster with title bar + activity compartment.

Cannot detect diagram type. Start your text with 'genogram', 'ecomap', 'pedigree', 'phylo', 'sociogram', 'timing', 'logic', 'circuit', 'blockdiagram', 'ladder', 'sld', 'entity-structure', 'fishbone', 'venn', 'flowchart', 'mindmap', 'matrix', or 'orgchart'.

Cross-boundary transitions (Outside --> Inside) are routed automatically — the Sugiyama layout pulls the source/target through the composite border.

6. Concurrent regions

Inside a composite, the -- separator (Mermaid) or --- (Schematex) splits the body into orthogonal regions that run concurrently.

state Active {
  [*] --> r1_idle
  r1_idle --> Connected : connect
  --
  [*] --> r2_idle
  r2_idle --> Working : start
}

Use fork and join to spawn / synchronize across regions:

Cannot detect diagram type. Start your text with 'genogram', 'ecomap', 'pedigree', 'phylo', 'sociogram', 'timing', 'logic', 'circuit', 'blockdiagram', 'ladder', 'sld', 'entity-structure', 'fishbone', 'venn', 'flowchart', 'mindmap', 'matrix', or 'orgchart'.

7. Notes

A short annotation can be attached to either side of any state.

note right of Checking : Calls /api/verify synchronously.
note left of Idle : Anonymous landing state

Multi-line notes use the Mermaid end note block form, or the Schematex { … } form:

note right of Authenticating
  Stores the JWT in localStorage
  on success.
end note

note left_of Idle {
  Anonymous landing state.
  Returns here on 401.
}

8. Self-transitions

A transition A --> A renders as a curved arc on the right side of the node.

Idle --> Idle : poll / refresh()

The label is placed beside the arc, outside the bounding box.

9. Layout direction

Schematex defaults to TB (top-to-bottom), matching Mermaid. Override on the header:

stateDiagram-v2
direction LR

[*] --> Loading
Loading --> Ready

Or with the Schematex bracket-attr form:

state "Order Lifecycle" [direction: TB]

[*] --> Pending
Pending --> Paid

BT and RL are accepted by the parser but normalized to TB and LR respectively (the layout engine doesn't yet flip the visual order).

10. Common mistakes

11. Grammar (EBNF)

document     = header statement*
header       = ("stateDiagram-v2" | "stateDiagram" | "state")
                ( title )? ( "[" attrs "]" )? NEWLINE
attrs        = attr ("," attr)*
attr         = "direction:" ("TB" | "LR")

statement    = comment
             | direction-stmt              %% direction LR / TB / BT / RL
             | state-decl
             | alias-decl                  %% state "Long" as ID
             | stereotype-decl             %% state ID <<choice|fork|join|end>>
             | pseudo-decl                 %% initial / final / choice / ... ID
             | composite-block             %% (state | composite) ID { ... }
             | label-stmt                  %% ID : description
             | transition
             | note-stmt
             | region-sep                  %% --  or  ---

transition   = (ID | "[*]") "-->" (ID | "[*]") ( ":" trans-label )? NEWLINE
trans-label  = trigger? ( "[" guard "]" )? ( "/" action )?

note-stmt    = "note" side ID ":" inline-text NEWLINE
             | "note" side ID NEWLINE  text-line+  ("end note" | "}") NEWLINE
side         = "left of" | "right of" | "left_of" | "right_of"

comment      = "%%" any | "#" any | "//" any

ID           = [A-Za-z_] [A-Za-z0-9_]*

Authoritative source: src/diagrams/state/parser.ts. If this diverges from the parser, the parser wins — please open an issue.

12. Standard compliance

Schematex is a strict superset of Mermaid stateDiagram-v2. Mermaid examples paste in unchanged; the additional UML 2.5 elements (activities, history, junction, terminate, full transition labels) are accepted alongside.

References:

• OMG UML 2.5.1 — Unified Modeling Language: https://www.omg.org/spec/UML/2.5.1/
• Harel (1987) — Statecharts: A visual formalism for complex systems, Science of Computer Programming 8(3)
• Mermaid stateDiagram-v2 — https://mermaid.js.org/syntax/stateDiagram.html

13. Roadmap

• BT / RL directions — currently normalized to TB / LR at parse time; visual flip pending
• Per-region direction override — direction LR inside a composite block (currently silently ignored)
• Submachine references — state Foo : Submachine stereotype rendering
• Internal transition compartment — explicit visual divider for tick [g] / a lines inside a state body