Skip to content
Tutorials Center
My learning

Topics

Lesson 20 of 39 ยท State and Component Diagrams

Composite States, Regions and History

Go beyond flat state diagrams: nested substates, orthogonal regions, choice and fork pseudostates, and history states, with a runnable hierarchical machine.

A flat state machine works for small lifecycles. Real objects quickly outgrow it. A media player has Stopped and Playing, but while it plays it is also Muted or not, and it is Buffering or not. If you draw one state for every combination you get a tangle of arrows. UML solves this with hierarchy (states inside states) and concurrency (independent parts that are active at the same time).

This lesson builds on State Machine Diagrams. You should already be comfortable reading event [guard] / action.

Composite (nested) states

A composite state contains substates. While the object is in a substate, it is also in the surrounding composite state. Transitions drawn to or from the outer boundary apply to every substate inside it, which removes a lot of duplicated arrows.

stateDiagram-v2
    [*] --> Off
    Off --> On : powerButton
    state On {
        [*] --> Idle
        Idle --> Playing : play
        Playing --> Paused : pause
        Paused --> Playing : play
        Playing --> Idle : stop
        Paused --> Idle : stop
    }
    On --> Off : powerButton

One arrow On --> Off replaces three arrows, one from each substate.

This is the principal benefit: a rule such as "pressing power from anywhere inside On turns the device off" is written once. When an event arrives, the machine first tries the transitions of the innermost active substate, then moves outward. That is called inner-first conflict resolution; an inner transition can override an outer one for the same event.

Entering and leaving follow a strict order. When a transition leaves Playing for Off, the exit actions run from the inside out (Playing, then On), and the entry actions of the target run afterward. Getting the order right matters when entry actions allocate resources and exit actions release them.

Orthogonal regions

An orthogonal region is a part of a composite state that runs in parallel with other parts. The state is divided by a dashed line, and the object is in one substate of each region at the same moment. In Mermaid you separate the regions with --.

stateDiagram-v2
    [*] --> Active
    state Active {
        [*] --> Silent
        Silent --> Loud : unmute
        Loud --> Silent : mute
        --
        [*] --> Normal
        Normal --> Buffering : stall
        Buffering --> Normal : filled
    }

Two independent regions: volume (Silent/Loud) and network (Normal/Buffering). Four combinations exist, but only four substates are drawn.

With flat states you would need 2 x 2 = 4 states and a web of arrows between them. With regions you add one state per new concern, so the diagram grows linearly instead of multiplicatively. The same idea scales: a third region for "subtitles on/off" adds two states, not eight.

Fork and join

A fork bar splits one incoming transition into several outgoing ones that enter different regions at the same time. A join bar waits until all incoming transitions arrived, then continues as one. They are drawn as thick bars, and Mermaid writes them as <<fork>> and <<join>>.

Choice and junction pseudostates

A choice (diamond) lets you branch after evaluating guards at runtime, using values computed by earlier actions. A junction merges or splits transition segments statically. In practice you draw a diamond with guards on the outgoing arrows, and one outgoing arrow should be [else] so the model is always complete.

stateDiagram-v2
    state check <<choice>>
    [*] --> Validating
    Validating --> check
    check --> Accepted : [score >= 50]
    check --> Rejected : [else]

History states

A composite state is normally restarted from its initial substate whenever it is entered. Sometimes you want it to remember where it was. A shallow history pseudostate, drawn as a small circle with an H, makes the machine resume in the last active substate of that level. A deep history (H*) remembers the whole nested configuration.

Typical example: a phone call is interrupted by an alarm. When the alarm ends, the media player should return to Paused or Playing, whichever it was in, rather than to Idle. Mermaid cannot draw history states, so UML tools or hand drawings are needed. When you write them in text, use a note such as "transition into On/H resumes the last substate".

Do not reach for history states early. If a diagram needs one, ask whether the object might be better split into two smaller state machines.

Hierarchical machine in code

The next example implements inner-first event handling and a shallow history. The state is a path such as On.Playing.

Python Hierarchy with inner-first dispatch and history

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

After pause and power off then on, the player returns to On.Paused, not On.Idle. That is the history state at work.

Concurrent regions in code

Each region is its own small machine. The composite state simply feeds each event to every region, and each region decides whether it cares.

Python Two orthogonal regions reacting to events

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Why use a composite state?

    An arrow from the composite boundary applies to every substate inside it.
  2. 2. An object has regions with 3 states and 4 states, active together. How many substates must be drawn?

    Regions are independent, so you draw 3 + 4 = 7 states instead of the 12 combinations a flat diagram needs.
  3. 3. What does a shallow history pseudostate do?

    History (H) lets a re-entered composite state continue where it left off.
  4. 4. Two events can both fire from a state. How should guards be written?

    Overlapping guards make the model ambiguous.

Summary

  • Composite states nest substates; outer transitions apply to all of them and inner transitions win on conflict.
  • Orthogonal regions run in parallel, so complexity adds up instead of multiplying.
  • Fork and join bars start and synchronize parallel regions; choice diamonds branch at runtime.
  • History states resume the last substate; Mermaid cannot draw them, so use notes in text diagrams.
  • Entry and exit actions run in a defined order, inside out on exit and outside in on entry.

Next: Component Diagrams