# Hierarchical state nodes
In statecharts, states can be nested within other states. These nested states are called compound states. To learn more, read the compound states section in our introduction to statecharts.
# API
The following example is a traffic light machine with nested states:
const pedestrianStates = {
initial: 'walk',
states: {
walk: {
on: {
PED_COUNTDOWN: { target: 'wait' }
}
},
wait: {
on: {
PED_COUNTDOWN: { target: 'stop' }
}
},
stop: {},
blinking: {}
}
};
const lightMachine = createMachine({
key: 'light',
initial: 'green',
states: {
green: {
on: {
TIMER: { target: 'yellow' }
}
},
yellow: {
on: {
TIMER: { target: 'red' }
}
},
red: {
on: {
TIMER: { target: 'green' }
},
...pedestrianStates
}
},
on: {
POWER_OUTAGE: { target: '.red.blinking' },
POWER_RESTORED: { target: '.red' }
}
});
The 'green'
and 'yellow'
states are simple states - they have no child states. In contrast, the 'red'
state is a compound state since it is composed of substates (the pedestrianStates
).
# Initial states
When a compound state is entered, its initial state is immediately entered as well. In the following traffic light machine example:
- the
'red'
state is entered - since
'red'
has an initial state of'walk'
, the{ red: 'walk' }
state is ultimately entered.
console.log(lightMachine.transition('yellow', { type: 'TIMER' }).value);
// => {
// red: 'walk'
// }
# Events
When a simple state does not handle an event
, that event
is propagated up to its parent state to be handled. In the following traffic light machine example:
- the
{ red: 'stop' }
state does not handle the'TIMER'
event - the
'TIMER'
event is sent to the'red'
parent state, which handles the event.
console.log(lightMachine.transition({ red: 'stop' }, { type: 'TIMER' }).value);
// => 'green'
If neither a state nor any of its ancestor (parent) states handle an event, no transition happens. In strict
mode (specified in the machine configuration), this will throw an error.
console.log(lightMachine.transition('green', { type: 'UNKNOWN' }).value);
// => 'green'