State Machines in React with XState

State machines make complex UI logic predictable. Here's how to use XState effectively.

Why State Machines#

// Traditional approach: scattered boolean flags
const [isLoading, setIsLoading] = useState(false);
const [isError, setIsError] = useState(false);
const [isSuccess, setIsSuccess] = useState(false);
const [data, setData] = useState(null);

// Problems:
// - Impossible states (isLoading && isError)
// - Easy to forget resetting flags
// - Hard to track all transitions

// State machine approach: explicit states
type State = 'idle' | 'loading' | 'success' | 'error';
// Only one state at a time, transitions are explicit

Basic State Machine#

import { createMachine, assign } from 'xstate';
import { useMachine } from '@xstate/react';

// Define the machine
const fetchMachine = createMachine({
  id: 'fetch',
  initial: 'idle',
  context: {
    data: null,
    error: null,
  },
  states: {
    idle: {
      on: {
        FETCH: 'loading',
      },
    },
    loading: {
      invoke: {
        src: 'fetchData',
        onDone: {
          target: 'success',
          actions: assign({
            data: (_, event) => event.data,
          }),
        },
        onError: {
          target: 'error',
          actions: assign({
            error: (_, event) => event.data,
          }),
        },
      },
    },
    success: {
      on: {
        REFRESH: 'loading',
        RESET: 'idle',
      },
    },
    error: {
      on: {
        RETRY: 'loading',
        RESET: 'idle',
      },
    },
  },
});

// Use in component
function DataFetcher({ url }: { url: string }) {
  const [state, send] = useMachine(fetchMachine, {
    services: {
      fetchData: async () => {
        const response = await fetch(url);
        if (!response.ok) throw new Error('Fetch failed');
        return response.json();
      },
    },
  });

  return (
    <div>
      {state.matches('idle') && (
        <button onClick={() => send('FETCH')}>Load Data</button>
      )}

      {state.matches('loading') && <Spinner />}

      {state.matches('success') && (
        <div>
          <pre>{JSON.stringify(state.context.data, null, 2)}</pre>
          <button onClick={() => send('REFRESH')}>Refresh</button>
        </div>
      )}

      {state.matches('error') && (
        <div>
          <p>Error: {state.context.error.message}</p>
          <button onClick={() => send('RETRY')}>Retry</button>
        </div>
      )}
    </div>
  );
}

Form State Machine#

interface FormContext {
  values: Record<string, string>;
  errors: Record<string, string>;
  touched: Record<string, boolean>;
}

const formMachine = createMachine<FormContext>({
  id: 'form',
  initial: 'editing',
  context: {
    values: {},
    errors: {},
    touched: {},
  },
  states: {
    editing: {
      on: {
        CHANGE: {
          actions: assign({
            values: (ctx, event) => ({
              ...ctx.values,
              [event.field]: event.value,
            }),
          }),
        },
        BLUR: {
          actions: [
            assign({
              touched: (ctx, event) => ({
                ...ctx.touched,
                [event.field]: true,
              }),
            }),
            'validateField',
          ],
        },
        SUBMIT: [
          {
            target: 'submitting',
            cond: 'isValid',
          },
          {
            actions: 'showErrors',
          },
        ],
      },
    },
    submitting: {
      invoke: {
        src: 'submitForm',
        onDone: 'success',
        onError: {
          target: 'editing',
          actions: assign({
            errors: (_, event) => event.data.errors,
          }),
        },
      },
    },
    success: {
      type: 'final',
    },
  },
}, {
  guards: {
    isValid: (ctx) => Object.keys(ctx.errors).length === 0,
  },
  actions: {
    validateField: assign({
      errors: (ctx, event) => {
        const errors = { ...ctx.errors };
        const value = ctx.values[event.field];

        if (!value) {
          errors[event.field] = 'Required';
        } else {
          delete errors[event.field];
        }

        return errors;
      },
    }),
    showErrors: assign({
      touched: (ctx) => {
        const touched: Record<string, boolean> = {};
        Object.keys(ctx.values).forEach(key => {
          touched[key] = true;
        });
        return touched;
      },
    }),
  },
});

// Usage
function ContactForm() {
  const [state, send] = useMachine(formMachine, {
    services: {
      submitForm: async (ctx) => {
        const response = await fetch('/api/contact', {
          method: 'POST',
          body: JSON.stringify(ctx.values),
        });
        if (!response.ok) {
          const data = await response.json();
          throw { errors: data.errors };
        }
      },
    },
  });

  const { values, errors, touched } = state.context;

  if (state.matches('success')) {
    return <p>Thank you for your message!</p>;
  }

  return (
    <form onSubmit={(e) => { e.preventDefault(); send('SUBMIT'); }}>
      <input
        value={values.email || ''}
        onChange={(e) => send({ type: 'CHANGE', field: 'email', value: e.target.value })}
        onBlur={() => send({ type: 'BLUR', field: 'email' })}
      />
      {touched.email && errors.email && <span>{errors.email}</span>}

      <button disabled={state.matches('submitting')}>
        {state.matches('submitting') ? 'Sending...' : 'Send'}
      </button>
    </form>
  );
}

Authentication Machine#

interface AuthContext {
  user: User | null;
  error: string | null;
}

type AuthEvent =
  | { type: 'LOGIN'; email: string; password: string }
  | { type: 'LOGOUT' }
  | { type: 'REFRESH' };

const authMachine = createMachine<AuthContext, AuthEvent>({
  id: 'auth',
  initial: 'checking',
  context: {
    user: null,
    error: null,
  },
  states: {
    checking: {
      invoke: {
        src: 'checkAuth',
        onDone: {
          target: 'authenticated',
          actions: assign({ user: (_, e) => e.data }),
        },
        onError: 'unauthenticated',
      },
    },
    unauthenticated: {
      on: {
        LOGIN: 'authenticating',
      },
    },
    authenticating: {
      invoke: {
        src: 'login',
        onDone: {
          target: 'authenticated',
          actions: assign({
            user: (_, e) => e.data,
            error: null,
          }),
        },
        onError: {
          target: 'unauthenticated',
          actions: assign({
            error: (_, e) => e.data.message,
          }),
        },
      },
    },
    authenticated: {
      on: {
        LOGOUT: 'loggingOut',
        REFRESH: 'refreshing',
      },
    },
    refreshing: {
      invoke: {
        src: 'refreshToken',
        onDone: {
          target: 'authenticated',
          actions: assign({ user: (_, e) => e.data }),
        },
        onError: 'unauthenticated',
      },
    },
    loggingOut: {
      invoke: {
        src: 'logout',
        onDone: {
          target: 'unauthenticated',
          actions: assign({ user: null }),
        },
        onError: 'authenticated',
      },
    },
  },
});

// Provider
const AuthContext = createContext<{
  state: any;
  send: any;
  user: User | null;
} | null>(null);

function AuthProvider({ children }: { children: React.ReactNode }) {
  const [state, send] = useMachine(authMachine, {
    services: {
      checkAuth: () => authService.getCurrentUser(),
      login: (_, event) => authService.login(event.email, event.password),
      logout: () => authService.logout(),
      refreshToken: () => authService.refresh(),
    },
  });

  return (
    <AuthContext.Provider value={{ state, send, user: state.context.user }}>
      {children}
    </AuthContext.Provider>
  );
}

Wizard/Multi-Step Form#

const wizardMachine = createMachine({
  id: 'wizard',
  initial: 'step1',
  context: {
    step1Data: {},
    step2Data: {},
    step3Data: {},
  },
  states: {
    step1: {
      on: {
        NEXT: {
          target: 'step2',
          actions: assign({
            step1Data: (_, e) => e.data,
          }),
        },
      },
    },
    step2: {
      on: {
        NEXT: {
          target: 'step3',
          actions: assign({
            step2Data: (_, e) => e.data,
          }),
        },
        BACK: 'step1',
      },
    },
    step3: {
      on: {
        SUBMIT: 'submitting',
        BACK: 'step2',
      },
    },
    submitting: {
      invoke: {
        src: 'submitWizard',
        onDone: 'complete',
        onError: 'step3',
      },
    },
    complete: {
      type: 'final',
    },
  },
});

function Wizard() {
  const [state, send] = useMachine(wizardMachine);

  const steps = {
    step1: <Step1 onNext={(data) => send({ type: 'NEXT', data })} />,
    step2: (
      <Step2
        onNext={(data) => send({ type: 'NEXT', data })}
        onBack={() => send('BACK')}
      />
    ),
    step3: (
      <Step3
        onSubmit={() => send('SUBMIT')}
        onBack={() => send('BACK')}
      />
    ),
    submitting: <Spinner />,
    complete: <Success />,
  };

  const currentStep = Object.keys(steps).find(step =>
    state.matches(step)
  ) as keyof typeof steps;

  return (
    <div>
      <ProgressBar current={currentStep} />
      {steps[currentStep]}
    </div>
  );
}

Parallel States#

const playerMachine = createMachine({
  id: 'player',
  type: 'parallel',
  states: {
    playback: {
      initial: 'paused',
      states: {
        paused: {
          on: { PLAY: 'playing' },
        },
        playing: {
          on: { PAUSE: 'paused' },
        },
      },
    },
    volume: {
      initial: 'normal',
      states: {
        muted: {
          on: { UNMUTE: 'normal' },
        },
        normal: {
          on: { MUTE: 'muted' },
        },
      },
    },
    fullscreen: {
      initial: 'off',
      states: {
        off: {
          on: { ENTER_FULLSCREEN: 'on' },
        },
        on: {
          on: { EXIT_FULLSCREEN: 'off' },
        },
      },
    },
  },
});

// Check multiple states
state.matches({ playback: 'playing', volume: 'muted' });

Testing State Machines#

import { interpret } from 'xstate';

describe('fetchMachine', () => {
  it('should transition to loading on FETCH', () => {
    const service = interpret(fetchMachine).start();

    service.send('FETCH');

    expect(service.state.matches('loading')).toBe(true);
  });

  it('should handle successful fetch', async () => {
    const mockData = { id: 1, name: 'Test' };

    const service = interpret(
      fetchMachine.withConfig({
        services: {
          fetchData: async () => mockData,
        },
      })
    ).start();

    service.send('FETCH');

    await waitFor(() => {
      expect(service.state.matches('success')).toBe(true);
      expect(service.state.context.data).toEqual(mockData);
    });
  });

  it('should handle fetch error', async () => {
    const service = interpret(
      fetchMachine.withConfig({
        services: {
          fetchData: async () => {
            throw new Error('Network error');
          },
        },
      })
    ).start();

    service.send('FETCH');

    await waitFor(() => {
      expect(service.state.matches('error')).toBe(true);
    });
  });
});

Best Practices#

Design:
✓ Model states explicitly
✓ Use context for data
✓ Define all transitions
✓ Handle all edge cases

Organization:
✓ One machine per feature
✓ Extract services and guards
✓ Use TypeScript for events
✓ Document state charts

Testing:
✓ Test all state transitions
✓ Test guards and actions
✓ Test service invocations
✓ Use model-based testing

State machines eliminate impossible states and make complex UI logic explicit. XState provides powerful tools for modeling workflows, forms, and async operations. Start simple and add complexity as needed. The upfront modeling investment pays off in reliability and maintainability.