createActor

Creates a new actor instance for the given actor logic with the provided options. When you create an actor from actor logic via createActor(logic), you implicitly create an actor system where the created actor is the root actor. Any actors spawned from this root actor and its descendants are part of that actor system.

Signature

function createActor<TLogic extends AnyActorLogic>(
  logic: TLogic,
  options?: ActorOptions<TLogic>
): Actor<TLogic>

Parameters

logic

ActorLogic

required

The actor logic to create an actor from.Actor logic can be:

A state machine created with createMachine()
Promise logic created with fromPromise()
Callback logic created with fromCallback()
Observable logic created with fromObservable() or fromEventObservable()
Transition logic created with fromTransition()

options

ActorOptions

Optional configuration for the actor.

Show properties

input

InputFrom<TLogic>

The input data to pass to the actor. Required if the actor logic requires input.

string

The custom ID for referencing this actor. Defaults to a unique generated ID.

systemId

string

The system ID to register this actor under for system-wide lookups.

snapshot

Snapshot<unknown>

Initializes actor logic from a specific persisted internal state.If the state is compatible with the actor logic, when the actor is started it will be at that persisted state. Actions from machine actors will not be re-executed, because they are assumed to have been already executed.

src

string | AnyActorLogic

The source actor logic identifier.

clock

Clock

The clock that is responsible for setting and clearing timeouts, such as delayed events and transitions.By default, the native setTimeout and clearTimeout functions are used.For testing, XState provides SimulatedClock.

logger

(...args: any[]) => void

Specifies the logger to be used for log(...) actions. Defaults to the native console.log(...) method.

inspect

Observer<InspectionEvent> | (event: InspectionEvent) => void

A callback function or observer object which can be used to inspect actor system updates.The inspection events that can be observed include:

@xstate.actor - An actor ref has been created in the system
@xstate.event - An event was sent from a source actor to a target actor
@xstate.snapshot - An actor emitted a snapshot due to a received event

Returns

actor

Actor<TLogic>

An Actor instance that can receive events, send events, and change its behavior.

Show properties

string

The unique identifier for this actor relative to its parent.

sessionId

string

The globally unique process ID for this invocation.

system

ActorSystem

The system to which this actor belongs.

send

(event: EventFromLogic<TLogic>) => void

Sends an event to the running actor to trigger a transition.

start

() => this

Starts the actor from the initial state. Must be called before the actor can receive events.

stop

() => this

Stops the actor and unsubscribes all listeners.

Subscribes an observer to the actor’s snapshot values.

(type: string, handler: Function) => Subscription

Registers an event listener for emitted events.

getSnapshot

() => SnapshotFrom<TLogic>

Reads the actor’s current snapshot synchronously.

getPersistedSnapshot

() => Snapshot<unknown>

Obtains the internal state of the actor, which can be persisted.

Examples

Creating and starting an actor

import { createActor, createMachine } from 'xstate';

const toggleMachine = createMachine({
  id: 'toggle',
  initial: 'inactive',
  states: {
    inactive: {
      on: { TOGGLE: 'active' }
    },
    active: {
      on: { TOGGLE: 'inactive' }
    }
  }
});

// Create the actor
const actor = createActor(toggleMachine);

// Subscribe to state changes
actor.subscribe((snapshot) => {
  console.log('State:', snapshot.value);
});

// Start the actor
actor.start();
// Logs: State: inactive

// Send events
actor.send({ type: 'TOGGLE' });
// Logs: State: active

// Stop the actor
actor.stop();

Actor with input

import { createActor, createMachine } from 'xstate';

const greetMachine = createMachine({
  types: {} as {
    context: { name: string; count: number };
    input: { name: string };
  },
  context: ({ input }) => ({
    name: input.name,
    count: 0
  }),
  initial: 'greeting',
  states: {
    greeting: {
      entry: ({ context }) => {
        console.log(`Hello, ${context.name}!`);
      }
    }
  }
});

const actor = createActor(greetMachine, {
  input: { name: 'Alice' }
});

actor.start();
// Logs: Hello, Alice!

Actor with inspection

import { createActor, createMachine } from 'xstate';

const machine = createMachine({
  initial: 'idle',
  states: {
    idle: {
      on: { START: 'running' }
    },
    running: {}
  }
});

const actor = createActor(machine, {
  inspect: (inspectionEvent) => {
    if (inspectionEvent.type === '@xstate.event') {
      console.log('Event:', inspectionEvent.event);
    }
    
    if (inspectionEvent.type === '@xstate.snapshot') {
      console.log('Snapshot:', inspectionEvent.snapshot.value);
    }
  }
});

actor.start();
actor.send({ type: 'START' });

Persisting and restoring actor state

import { createActor, createMachine } from 'xstate';

const counterMachine = createMachine({
  initial: 'active',
  context: { count: 0 },
  states: {
    active: {
      on: {
        INCREMENT: {
          actions: assign({ count: ({ context }) => context.count + 1 })
        }
      }
    }
  }
});

// Create and use the actor
const actor1 = createActor(counterMachine);
actor1.start();
actor1.send({ type: 'INCREMENT' });
actor1.send({ type: 'INCREMENT' });

// Persist the state
const persistedState = actor1.getPersistedSnapshot();

// Later, restore the state
const actor2 = createActor(counterMachine, {
  snapshot: persistedState
});
actor2.start();

console.log(actor2.getSnapshot().context.count); // 2

Using different actor logics

import { createActor, fromPromise, fromCallback } from 'xstate';

// Promise actor
const promiseLogic = fromPromise(async ({ input }: { input: number }) => {
  const response = await fetch(`/api/data/${input}`);
  return response.json();
});

const promiseActor = createActor(promiseLogic, { input: 42 });
promiseActor.start();

// Callback actor
const callbackLogic = fromCallback(({ sendBack }) => {
  const interval = setInterval(() => {
    sendBack({ type: 'TICK' });
  }, 1000);

  return () => clearInterval(interval);
});

const callbackActor = createActor(callbackLogic);
callbackActor.subscribe((snapshot) => {
  console.log('Callback actor snapshot:', snapshot);
});
callbackActor.start();

Notes

Actors must be started with .start() before they can receive events or emit snapshots
Only root actors (those without a parent) can be stopped with .stop()
When an actor is stopped, all of its observers are automatically unsubscribed
The actor system is created when the root actor is created and manages all spawned child actors

Core API

Actions

Guards

Actors

Utilities

Signature

Parameters

Returns

Examples

Creating and starting an actor

Actor with input

Actor with inspection

Persisting and restoring actor state

Using different actor logics

Notes

See also

Build docs developers (and LLMs) love

Core API

Actions

Guards

Actors

Utilities

Documentation Index

​Signature

​Parameters

​Returns

​Examples

​Creating and starting an actor

​Actor with input

​Actor with inspection

​Persisting and restoring actor state

​Using different actor logics

​Notes

​See also

Build docs developers (and LLMs) love

Signature

Parameters

Returns

Examples

Creating and starting an actor

Actor with input

Actor with inspection

Persisting and restoring actor state

Using different actor logics

Notes

See also