Creates an action object that will execute actions that are queued by theDocumentation 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.
enqueue(action) function.
import { enqueueActions } from 'xstate';
Signature
function enqueueActions<
TContext extends MachineContext,
TExpressionEvent extends EventObject,
TParams extends ParameterizedObject['params'] | undefined,
TEvent extends EventObject = TExpressionEvent,
TActor extends ProvidedActor = ProvidedActor,
TAction extends ParameterizedObject = ParameterizedObject,
TGuard extends ParameterizedObject = ParameterizedObject,
TDelay extends string = never,
TEmitted extends EventObject = EventObject
>(
collect: CollectActions<
TContext,
TExpressionEvent,
TParams,
TEvent,
TActor,
TAction,
TGuard,
TDelay,
TEmitted
>
): ActionFunction
Parameters
A function that receives a
CollectActionsArg object and enqueues actions. The function receives:Show properties
Show properties
The current state context.
The event that triggered this action.
Function to enqueue actions. Can be called directly with an action, or use helper methods:
enqueue.assign(...)- enqueue an assign actionenqueue.cancel(...)- enqueue a cancel actionenqueue.raise(...)- enqueue a raise actionenqueue.sendTo(...)- enqueue a sendTo actionenqueue.sendParent(...)- enqueue a sendParent actionenqueue.spawnChild(...)- enqueue a spawnChild actionenqueue.stopChild(...)- enqueue a stopChild actionenqueue.emit(...)- enqueue an emit action
Function to evaluate guards. Returns
true if the guard passes, false otherwise.Reference to the current actor.
Reference to the actor system.
Returns
An action function that executes the enqueued actions when invoked.
Examples
Basic usage
import { createMachine, enqueueActions } from 'xstate';
const machine = createMachine({
entry: enqueueActions(({ enqueue, check }) => {
enqueue.assign({ count: 0 });
if (check('someGuard')) {
enqueue.assign({ count: 1 });
}
enqueue('someAction');
})
});
Conditional actions
const machine = createMachine({
types: {} as {
context: { temperature: number };
events: { type: 'CHECK_TEMP' };
},
context: { temperature: 20 },
on: {
CHECK_TEMP: {
actions: enqueueActions(({ enqueue, context, check }) => {
if (context.temperature > 30) {
enqueue.raise({ type: 'OVERHEAT' });
enqueue.emit({ type: 'warning', level: 'high' });
} else if (context.temperature > 25) {
enqueue.emit({ type: 'warning', level: 'medium' });
}
})
}
}
});
Dynamic action sequences
const machine = createMachine({
types: {} as {
context: { items: string[] };
},
context: { items: [] },
on: {
PROCESS_ITEMS: {
actions: enqueueActions(({ enqueue, context }) => {
context.items.forEach((item, index) => {
enqueue.raise({
type: 'PROCESS_ITEM',
item,
index
});
});
enqueue.raise({ type: 'PROCESSING_COMPLETE' });
})
}
}
});
Using check with guards
const machine = createMachine(
{
types: {} as {
context: { count: number };
},
context: { count: 0 },
on: {
INCREMENT: {
actions: enqueueActions(({ enqueue, check, context }) => {
enqueue.assign({
count: context.count + 1
});
if (check({ type: 'isMax' })) {
enqueue.raise({ type: 'MAX_REACHED' });
enqueue.emit({ type: 'limit.reached' });
}
})
}
}
},
{
guards: {
isMax: ({ context }) => context.count >= 10
}
}
);
Combining multiple action types
const machine = createMachine({
types: {} as {
context: {
status: string;
childRef: ActorRef<any> | null;
};
},
context: {
status: 'idle',
childRef: null
},
on: {
START_PROCESS: {
actions: enqueueActions(({ enqueue, context }) => {
// Update context
enqueue.assign({ status: 'processing' });
// Spawn a child actor
enqueue.spawnChild('workerMachine', { id: 'worker' });
// Send to child
enqueue.sendTo('worker', { type: 'START' });
// Emit to observers
enqueue.emit({ type: 'process.started' });
// Schedule a timeout
enqueue.raise(
{ type: 'TIMEOUT' },
{ delay: 5000, id: 'processTimeout' }
);
})
},
CANCEL: {
actions: enqueueActions(({ enqueue }) => {
enqueue.cancel('processTimeout');
enqueue.stopChild('worker');
enqueue.assign({ status: 'cancelled' });
})
}
}
});
Notes
Use
enqueueActions when you need to conditionally execute actions or dynamically determine which actions to run based on context, events, or guards.Actions are enqueued in the order they are called and will be executed in that same order.
The
check() function evaluates guards synchronously. Make sure your guards are pure functions that don’t have side effects.