xstate-event-emitter

XState v5 Event Emitter

Emitted events go outward from the actor to external listeners — the opposite of actor.send() which sends events inward.

emit() Action Creator

Emit events from state machine transitions:

import { setup, emit, createActor } from 'xstate';

const machine = setup({
  types: {
    emitted: {} as
      | { type: 'notification'; message: string }
      | { type: 'error'; code: number },
  },
}).createMachine({
  on: {
    submit: {
      actions: emit({ type: 'notification', message: 'Submitted!' }),
    },
  },
});

const actor = createActor(machine);

// Subscribe to emitted events
actor.on('notification', (event) => {
  console.log(event.message); // 'Submitted!'
});

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

Static vs Dynamic emit

setup({
  actions: {
    // Static — fixed event
    emitStatic: emit({
      type: 'notification',
      message: 'Hello',
    }),

    // Dynamic — based on context/event
    emitDynamic: emit(({ context }) => ({
      type: 'notification',
      message: 'Count is ' + context.count,
    })),
  },
}).createMachine({ /* ... */ });

Listening for Emitted Events

actor.on(eventType, handler)

Returns a subscription object:

const actor = createActor(machine);

const sub = actor.on('notification', (event) => {
  console.log(event.message);
});

actor.start();

// Later: stop listening
sub.unsubscribe();

Wildcard Listener

Listen to all emitted events with '*':

actor.on('*', (emitted) => {
  console.log(emitted); // Union of all emitted event types
});

Emitting from Actor Logic Types

All actor logic creators support emit:

Promise Actors

const logic = fromPromise(async ({ emit }) => {
  emit({ type: 'progress', percent: 50 });
  const result = await doWork();
  emit({ type: 'progress', percent: 100 });
  return result;
});

Callback Actors

const logic = fromCallback(({ emit }) => {
  const interval = setInterval(() => {
    emit({ type: 'tick' });
  }, 1000);

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

Observable Actors

const logic = fromObservable(({ emit }) => {
  emit({ type: 'started' });
  return interval(1000);
});

Transition Actors

const logic = fromTransition((state, event, { emit }) => {
  if (event.type === 'INCREMENT') {
    emit({ type: 'changed', value: state.count + 1 });
    return { count: state.count + 1 };
  }
  return state;
}, { count: 0 });

TypeScript

Strongly type emitted events in setup():

const machine = setup({
  types: {
    emitted: {} as
      | { type: 'notification'; message: string }
      | { type: 'error'; error: Error },
  },
}).createMachine({ /* ... */ });

const actor = createActor(machine);

// Fully typed — event.message is string
actor.on('notification', (event) => {
  console.log(event.message);
});

// Type error: 'unknown' is not a valid emitted event
// actor.on('unknown', (event) => {});

Use Cases

Decoupling UI Effects from Machine Logic

const formMachine = setup({
  types: {
    emitted: {} as
      | { type: 'toast'; message: string; variant: 'success' | 'error' }
      | { type: 'analytics'; event: string },
  },
}).createMachine({
  states: {
    submitting: {
      invoke: {
        src: 'submitForm',
        onDone: {
          target: 'success',
          actions: [
            emit({ type: 'toast', message: 'Saved!', variant: 'success' }),
            emit(({ context }) => ({
              type: 'analytics',
              event: 'form_submitted',
            })),
          ],
        },
        onError: {
          target: 'error',
          actions: emit({ type: 'toast', message: 'Failed', variant: 'error' }),
        },
      },
    },
    success: {},
    error: {},
  },
});

// In the UI layer — connect to whatever toast/analytics system you use
const actor = createActor(formMachine);
actor.on('toast', ({ message, variant }) => showToast(message, variant));
actor.on('analytics', ({ event }) => analytics.track(event));

vs sendParent / vs context

Pattern	When to Use
emit()	External side effects (toasts, analytics, logging)
sendTo(parentRef)	Parent-child actor communication
assign()	Data that the machine needs to track internally

emit() is best when the machine shouldn't know or care about what happens with the event.