raise

API reference for the raise action

Raises an event. This places the event in the internal event queue, so that the event is immediately consumed by the machine in the current step.

import { raise } from 'xstate';

Signature

function raise<
  TContext extends MachineContext,
  TExpressionEvent extends EventObject,
  TEvent extends EventObject,
  TParams extends ParameterizedObject['params'] | undefined,
  TDelay extends string = never,
  TUsedDelay extends TDelay = never
>(
  eventOrExpr:
    | DoNotInfer<TEvent>
    | SendExpr<TContext, TExpressionEvent, TParams, DoNotInfer<TEvent>, TEvent>,
  options?: RaiseActionOptions<TContext, TExpressionEvent, TParams, DoNotInfer<TEvent>, TUsedDelay>
): ActionFunction<
  TContext,
  TExpressionEvent,
  TEvent,
  TParams,
  never,
  never,
  never,
  TDelay,
  never
>

Parameters

eventOrExpr · EventObject | SendExpr · required

The event to raise. Can be either:

• An event object (e.g., { type: 'NEXT' })
• A function that receives ActionArgs and returns an event object

Only event objects may be used with raise. String event types are not allowed. Use raise({ type: "EVENT_NAME" }) instead of raise("EVENT_NAME").

options · RaiseActionOptions

Optional configuration object:

Show properties

id · string

The unique identifier for this raised event. Used with cancel() to cancel delayed raises.

delay · string | number | DelayExpr

The delay before raising the event:

• Number: milliseconds to delay
• String: reference to a delay defined in delays implementation
• Function: expression that receives ActionArgs and returns delay in milliseconds

If no delay is specified, the event is raised immediately.

Returns

ActionFunction · ActionFunction

An action function that raises the event when executed.

Examples

Basic usage

import { createMachine, raise } from 'xstate';

const machine = createMachine({
  initial: 'idle',
  states: {
    idle: {
      on: {
        START: {
          actions: raise({ type: 'NEXT' }),
          target: 'working'
        },
        NEXT: {
          target: 'done'
        }
      }
    },
    working: {},
    done: {}
  }
});

Dynamic event

const machine = createMachine({
  context: { value: 0 },
  on: {
    INCREMENT: {
      actions: raise(({ context }) => ({
        type: 'UPDATE',
        value: context.value + 1
      }))
    },
    UPDATE: {
      actions: assign({
        value: ({ event }) => event.value
      })
    }
  }
});

Delayed raise

const machine = createMachine({
  initial: 'waiting',
  states: {
    waiting: {
      entry: raise(
        { type: 'TIMEOUT' },
        { delay: 1000, id: 'timeout' }
      ),
      on: {
        CANCEL: {
          actions: cancel('timeout')
        },
        TIMEOUT: {
          target: 'done'
        }
      }
    },
    done: {}
  }
});

Using named delays

const machine = createMachine(
  {
    initial: 'idle',
    states: {
      idle: {
        entry: raise({ type: 'START' }, { delay: 'shortDelay' }),
        on: {
          START: 'active'
        }
      },
      active: {}
    }
  },
  {
    delays: {
      shortDelay: 500
    }
  }
);

Custom actions should not call raise() directly, as it is not imperative. Use it only in machine configurations.