Final states

A final state is a state that represents the completion or successful termination of a machine. It is defined by the type: 'final' property on a state node:

import { createMachine, createActor } from 'xstate';

const feedbackMachine = createMachine({
  initial: 'prompt',
  states: {
    prompt: {
      /* ... */
    },
    thanks: {
      /* ... */
    },
    closed: {
      type: 'final',
    },
    // ...
  },
  on: {
    'feedback.close': {
      target: '.closed',
    },
  },
});

When a machine reaches the final state, it can no longer receive any events, and anything running inside it is canceled and cleaned up. The box with a surrounding border icon represents the final state.

A machine can have multiple final states or no final states.

• A state machine can have zero or more final states. Some machines may run indefinitely and not need to terminate.
• Final states can have output data, which is sent to the parent machine when the machine terminates.
• When a machine reaches a top-level final state, it terminates.
• Final states cannot have transitions

Top-level final states

A top-level final state is a final state that is a direct child state of the machine. When the machine reaches a top-level final state, the machine will terminate. When a machine terminates, it can no longer receive events nor transition.

Child final states

When a child final state of a parent (compound) state is reached, that parent state is considered "done". The onDone transition of that parent state is automatically taken.

import { createMachine } from 'xstate';

const coffeeMachine = createMachine({
  initial: 'preparation',
  states: {
    preparation: {
      initial: 'weighing',
      states: {
        weighing: {
          on: {
            weighed: {
              target: 'grinding'
            }
          }
        },
        grinding: {
          on: {
            ground: 'ready'
          }
        },
        ready: {
          // Child final state of parent state 'preparation'
          type: 'final'
        }
      },
      // Transition will be taken when child final state is reached
      onDone: {
        target: 'brewing'
      }
    },
    brewing: {
      // ...
    }
  }
});

Final states in parallel states

When all regions of a parallel state are "done", the parallel state is considered "done". The onDone transition of the parallel state is taken.

In this example, the preparation state is a parallel state with two regions: beans and water. When both regions are done, the preparation state is done, and the brewing state is entered.

import { createMachine, createActor } from 'xstate';

const coffeeMachine = createMachine({
  initial: 'preparation',
  states: {
    preparation: {
      type: 'parallel',
      states: {
        beans: {
          initial: 'grinding',
          states: {
            grinding: {
              on: {
                grindingComplete: 'ground',
              },
            },
            ground: {
              type: 'final',
            },
          },
        },
        water: {
          initial: 'heating',
          states: {
            heating: {
              always: {
                guard: 'waterBoiling',
                target: 'heated',
              },
            },
            heated: {
              type: 'final',
            },
          },
        },
      },
      onDone: 'brewing',
    },
    brewing: {},
  },
});

Output

When a machine reaches its top-level final state, it can produce output data. You can specify this output data in the .output property of the machine config:

import { createMachine, createActor } from 'xstate';

const currencyMachine = createMachine({
  // ...
  states: {
    converting: {
      // ...
    },
    converted: {
      type: 'final',
    },
  },
  output: ({ context }) => ({
    amount: context.amount,
    currency: context.currency,
  }),
});

const currencyActor = createActor(currencyMachine, {
  input: {
    amount: 10,
    fromCurrency: 'USD',
    toCurrency: 'EUR',
  },
});

currencyActor.subscribe({
  complete() {
    console.log(currencyActor.getSnapshot().output);
    // logs e.g. { amount: 12, currency: 'EUR' }
  },
});

The .output property can also be a static value:

import { createMachine, createActor } from 'xstate';

const processMachine = createMachine({
  // ...
  output: {
    message: 'Process completed.',
  },
});

Final states cheatsheet

import { createMachine } from 'xstate';

const feedbackMachine = createMachine({
  initial: 'prompt',
  states: {
    prompt: {
      /* ... */
    },
    thanks: {
      /* ... */
    },
    closed: {
      type: 'final',
    },
    // ...
  },
  on: {
    'feedback.close': {
      target: '.closed',
    },
  },
});

Cheatsheet: final states in parallel states

import { createMachine} from 'xstate';

const coffeeMachine = createMachine({
  initial: 'preparation',
  states: {
    preparation: {
      type: 'parallel',
      states: {
        beans: {
          initial: 'grinding',
          states: {
            grinding: {
              on: {
                grindingComplete: 'ground',
              },
            },
            ground: {
              type: 'final',
            },
          },
        },
        water: {
          initial: 'heating',
          states: {
            heating: {
              always: {
                guard: 'waterBoiling',
                target: 'heated',
              },
            },
            heated: {
              type: 'final',
            },
          },
        },
      },
      onDone: 'brewing',
    },
    brewing: {},
  },
});