State diagrams: composite states and history

简介 / Introduction

State machines describe the lifecycle of objects and protocol state transitions. Composite states bundle multiple sub-states under one high-level state, reducing diagram clutter; history states remember the last active sub-state on exit, enabling “resume where you left off”. This article uses the same business scenario (a login flow) to demonstrate PlantUML and Mermaid syntax side by side.

PlantUML 版

PlantUML supports full composite states plus shallow/deep history markers:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39

@startuml
skinparam state {
  BackgroundColor<<Composite>> #E3F2FD
  BackgroundColor<<History>> #FFF9C4
  BackgroundColor<<Final>> #FFCDD2
  FontSize 13
}
title Login State Machine — PlantUML Composite State

[*] --> LOGGING

state LOGGING {
  [*] --> IDLE
  IDLE --> VERIFYING : Enter credentials\nClick login
  VERIFYING --> PASSWORD_ERROR : Wrong password\n<max retries
  PASSWORD_ERROR --> IDLE : Retry
  VERIFYING --> MFA_REQUIRED : MFA required
  MFA_REQUIRED --> MFA_CHALLENGE : Send code
  MFA_CHALLENGE --> MFA_OK : Code valid
  MFA_CHALLENGE --> MFA_FAIL : Timeout/wrong\n>max attempts
  MFA_FAIL --> [*]

  -- History track --
  state "H" as H <<History>>
  state "H*" as HSTAR <<DeepHistory>>
  IDLE --> H : Exit
  H --> IDLE : Resume
  HSTAR --> MFA_CHALLENGE : Deep resume
}

LOGGING --> AUTHENTICATED : MFA_OK\nor direct pass
AUTHENTICATED --> LOGGING : Log out
AUTHENTICATED --> [*]

note right of LOGGING
  H : shallow history — restores last sub-state
  H* : deep history — recurses across levels
end note
@enduml

PlantUML key points:

• state <Name> { ... } defines a composite state; sub-states and branches live inside.
• [*] inside the composite block marks the default entry sub-state.
• H <<History>> is shallow history (one level); H* <<DeepHistory>> resumes across arbitrary depth.
• Stereotypes <<History>> / <<DeepHistory>> need matching skinparam state BackgroundColor to render with distinct colors.

Mermaid 版

Mermaid does not support composite states or history states. Mermaid’s stateDiagram only supports flat orthogonal regions (separated by --), no nested state blocks, and no H / H* history markers. Below is the equivalent flat representation — it cannot express “resume from last interrupted sub-state”:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

stateDiagram-v2
  direction TB
  [*] --> IDLE
  IDLE --> VERIFYING : Enter credentials\nClick login
  VERIFYING --> PASSWORD_ERROR : Wrong password
  PASSWORD_ERROR --> IDLE : Retry
  VERIFYING --> MFA_REQUIRED : MFA required
  MFA_REQUIRED --> MFA_CHALLENGE : Send code
  MFA_CHALLENGE --> MFA_OK : Code valid
  MFA_CHALLENGE --> MFA_FAIL : Timeout/wrong
  MFA_FAIL --> [*]
  MFA_OK --> AUTHENTICATED
  AUTHENTICATED --> IDLE : Log out
  AUTHENTICATED --> [*]

  note right of MFA_CHALLENGE
    Mermaid has no composite states.
    No history state — cannot remember
    the last interrupted sub-state.
  end note

If your domain requires composite/history semantics, use PlantUML. Mermaid (v11) currently has no plans to support them.

对比 / Side-by-side

小结 / Wrap-up

PlantUML’s state machine notation fully supports composite states and history states, making it suitable for complex protocols and workflow engines. Mermaid stateDiagram targets lightweight use cases; if your design depends on “interrupt-and-resume” semantics, stick with PlantUML. Choose based on state complexity — Mermaid for quick flat flows, PlantUML when depth and history matter.