Documentation Index
Fetch the complete documentation index at: https://mintlify.com/statelyai/xstate/llms.txt
Use this file to discover all available pages before exploring further.
Stops a child actor.
import { stopChild } from 'xstate';
Signature
function stopChild<
TContext extends MachineContext,
TExpressionEvent extends EventObject,
TParams extends ParameterizedObject['params'] | undefined,
TEvent extends EventObject
>(
actorRef: ResolvableActorRef<TContext, TExpressionEvent, TParams, TEvent>
): StopAction<TContext, TExpressionEvent, TParams, TEvent>
Parameters
actorRef
string | ActorRef | ResolvableActorRef
required
The actor to stop. Can be:
- String: the ID of a child actor
ActorRef: direct reference to an actor- Function: expression that receives
ActionArgs and returns an actor ref or ID
Returns
An action function that stops the child actor when executed.
Examples
Stop by ID
import { createMachine, spawnChild, stopChild } from 'xstate';
const machine = createMachine({
on: {
SPAWN: {
actions: spawnChild(childMachine, { id: 'myChild' })
},
STOP: {
actions: stopChild('myChild')
}
}
});
Stop by actor ref
const machine = createMachine({
types: {} as {
context: { childRef: ActorRef<typeof childMachine> | null };
},
context: { childRef: null },
on: {
SPAWN: {
actions: assign({
childRef: ({ spawn }) => spawn(childMachine)
})
},
STOP: {
actions: stopChild(({ context }) => context.childRef!)
}
}
});
Dynamic actor ID
const machine = createMachine({
types: {} as {
events:
| { type: 'SPAWN'; id: string }
| { type: 'STOP'; id: string };
},
on: {
SPAWN: {
actions: spawnChild('worker', {
id: ({ event }) => event.id
})
},
STOP: {
actions: stopChild(({ event }) => event.id)
}
}
});
Stop on state exit
const machine = createMachine({
initial: 'running',
states: {
running: {
entry: spawnChild(workerMachine, { id: 'worker' }),
exit: stopChild('worker'),
on: {
FINISH: 'done'
}
},
done: {}
}
});
Stop multiple children
import { enqueueActions } from 'xstate';
const machine = createMachine({
types: {} as {
context: { workerIds: string[] };
},
context: { workerIds: ['worker1', 'worker2', 'worker3'] },
on: {
SPAWN_ALL: {
actions: enqueueActions(({ enqueue, context }) => {
context.workerIds.forEach((id) => {
enqueue.spawnChild('worker', { id });
});
})
},
STOP_ALL: {
actions: enqueueActions(({ enqueue, context }) => {
context.workerIds.forEach((id) => {
enqueue.stopChild(id);
});
})
}
}
});
Conditional stop
const machine = createMachine({
types: {} as {
context: { shouldKeepAlive: boolean };
},
context: { shouldKeepAlive: false },
initial: 'active',
states: {
active: {
entry: spawnChild(taskMachine, { id: 'task' }),
on: {
COMPLETE: 'done'
}
},
done: {
always: [
{
guard: ({ context }) => !context.shouldKeepAlive,
actions: stopChild('task')
}
]
}
}
});
Notes
When a child actor is stopped, it is removed from the machine’s snapshot and will no longer be accessible via its ID or reference.
Stopping a child actor enqueues a stop event in the child’s mailbox. Any events already in the child’s queue will be processed before the actor stops.
If an actor is stopped before it has started (e.g., stopped in the same macrostep it was spawned), it will be prevented from starting.
The stop export is deprecated. Use stopChild instead.