React State Machines in 2026: XState v5, useReducer Patterns, and Complex UI Flows

Most UI bugs live in state transitions — the user clicks "Submit", the button gets disabled, the spinner appears, then the request fails, but now the form is in an ambiguous half-submitted state with no way out. Finite state machines prevent this by making impossible states impossible to represent.

This post covers two approaches: lightweight useReducer state machines for simple flows, and XState v5 for complex multi-step workflows with parallel states, delayed transitions, and actor-based orchestration. We cover multi-step wizards, form submission flows, and testing state transitions.

---

The Core Insight: Enumerate Valid States

// ❌ Boolean soup — impossible states are possible
const [isLoading, setIsLoading] = useState(false);
const [hasError, setHasError] = useState(false);
const [isSuccess, setIsSuccess] = useState(false);
// Bug: isLoading=true AND isSuccess=true is representable but nonsensical

// ✅ Discriminated union — only valid states exist
type SubmitState =
  | { status: "idle" }
  | { status: "submitting" }
  | { status: "success"; data: OrderConfirmation }
  | { status: "error"; error: string };

// Can't be loading AND successful at the same time
const [state, setState] = useState<SubmitState>({ status: "idle" });

---

useReducer State Machine (Lightweight)

For simpler flows, a typed reducer with a finite state enum is sufficient:

// hooks/useCheckoutFlow.ts
type CheckoutState =
  | { step: "cart"; cartId: string }
  | { step: "shipping"; cartId: string; shippingAddress?: Address }
  | { step: "payment"; cartId: string; shippingAddress: Address }
  | { step: "review"; cartId: string; shippingAddress: Address; paymentMethod: PaymentMethod }
  | { step: "submitting"; cartId: string }
  | { step: "success"; orderId: string }
  | { step: "error"; previousStep: string; error: string };

type CheckoutEvent =
  | { type: "NEXT" }
  | { type: "BACK" }
  | { type: "SET_SHIPPING"; address: Address }
  | { type: "SET_PAYMENT"; method: PaymentMethod }
  | { type: "SUBMIT" }
  | { type: "SUCCESS"; orderId: string }
  | { type: "FAILURE"; error: string }
  | { type: "RETRY" };

function checkoutReducer(state: CheckoutState, event: CheckoutEvent): CheckoutState {
  switch (state.step) {
    case "cart":
      if (event.type === "NEXT") return { step: "shipping", cartId: state.cartId };
      return state;

    case "shipping":
      if (event.type === "SET_SHIPPING") return { ...state, shippingAddress: event.address };
      if (event.type === "NEXT" && state.shippingAddress) {
        return { step: "payment", cartId: state.cartId, shippingAddress: state.shippingAddress };
      }
      if (event.type === "BACK") return { step: "cart", cartId: state.cartId };
      return state;

    case "payment":
      if (event.type === "SET_PAYMENT") return { ...state, paymentMethod: event.method };
      if (event.type === "NEXT" && state.paymentMethod) {
        return {
          step: "review",
          cartId: state.cartId,
          shippingAddress: state.shippingAddress,
          paymentMethod: state.paymentMethod,
        };
      }
      if (event.type === "BACK") {
        return { step: "shipping", cartId: state.cartId, shippingAddress: state.shippingAddress };
      }
      return state;

    case "review":
      if (event.type === "SUBMIT") return { step: "submitting", cartId: state.cartId };
      if (event.type === "BACK") {
        return {
          step: "payment",
          cartId: state.cartId,
          shippingAddress: state.shippingAddress,
          paymentMethod: state.paymentMethod,
        };
      }
      return state;

    case "submitting":
      if (event.type === "SUCCESS") return { step: "success", orderId: event.orderId };
      if (event.type === "FAILURE") return { step: "error", previousStep: "review", error: event.error };
      return state;

    case "error":
      if (event.type === "RETRY") return { step: "review", ...reconstructReviewState(state) };
      return state;

    default:
      return state;
  }
}

export function useCheckoutFlow(cartId: string) {
  const [state, dispatch] = useReducer(checkoutReducer, {
    step: "cart",
    cartId,
  });

  const submit = useCallback(async () => {
    dispatch({ type: "SUBMIT" });
    try {
      const order = await createOrder(cartId);
      dispatch({ type: "SUCCESS", orderId: order.id });
    } catch (err) {
      dispatch({ type: "FAILURE", error: err instanceof Error ? err.message : "Unknown error" });
    }
  }, [cartId]);

  return { state, dispatch, submit };
}

---

XState v5: Complex Multi-State Flows

XState v5 (released 2024) introduces actors as the core abstraction, with setup() for full TypeScript inference:

// machines/checkout.machine.ts
import { setup, assign, fromPromise } from "xstate";

interface CheckoutContext {
  cartId: string;
  shippingAddress: Address | null;
  paymentMethod: PaymentMethod | null;
  orderId: string | null;
  error: string | null;
}

export const checkoutMachine = setup({
  types: {
    context: {} as CheckoutContext,
    events: {} as
      | { type: "NEXT" }
      | { type: "BACK" }
      | { type: "SET_SHIPPING"; address: Address }
      | { type: "SET_PAYMENT"; method: PaymentMethod }
      | { type: "SUBMIT" }
      | { type: "RETRY" },
  },
  actors: {
    submitOrder: fromPromise(async ({ input }: { input: { cartId: string } }) => {
      const res = await fetch("/api/orders", {
        method: "POST",
        headers: { "Content-Type": "application/json" },
        body: JSON.stringify({ cartId: input.cartId }),
      });
      if (!res.ok) throw new Error(await res.text());
      return res.json() as Promise<{ orderId: string }>;
    }),
  },
  guards: {
    hasShipping: ({ context }) => context.shippingAddress !== null,
    hasPayment: ({ context }) => context.paymentMethod !== null,
  },
}).createMachine({
  id: "checkout",
  initial: "cart",
  context: ({ input }: { input: { cartId: string } }) => ({
    cartId: input.cartId,
    shippingAddress: null,
    paymentMethod: null,
    orderId: null,
    error: null,
  }),
  states: {
    cart: {
      on: {
        NEXT: "shipping",
      },
    },
    shipping: {
      on: {
        SET_SHIPPING: {
          actions: assign({ shippingAddress: ({ event }) => event.address }),
        },
        NEXT: {
          target: "payment",
          guard: "hasShipping",
        },
        BACK: "cart",
      },
    },
    payment: {
      on: {
        SET_PAYMENT: {
          actions: assign({ paymentMethod: ({ event }) => event.method }),
        },
        NEXT: {
          target: "review",
          guard: "hasPayment",
        },
        BACK: "shipping",
      },
    },
    review: {
      on: {
        SUBMIT: "submitting",
        BACK: "payment",
      },
    },
    submitting: {
      invoke: {
        src: "submitOrder",
        input: ({ context }) => ({ cartId: context.cartId }),
        onDone: {
          target: "success",
          actions: assign({ orderId: ({ event }) => event.output.orderId }),
        },
        onError: {
          target: "error",
          actions: assign({ error: ({ event }) => String(event.error) }),
        },
      },
    },
    success: { type: "final" },
    error: {
      on: {
        RETRY: {
          target: "review",
          actions: assign({ error: null }),
        },
      },
    },
  },
});

---

Using XState in React

// components/Checkout/CheckoutWizard.tsx
"use client";

import { useMachine } from "@xstate/react";
import { checkoutMachine } from "@/machines/checkout.machine";
import { CartStep } from "./CartStep";
import { ShippingStep } from "./ShippingStep";
import { PaymentStep } from "./PaymentStep";
import { ReviewStep } from "./ReviewStep";
import { SuccessStep } from "./SuccessStep";

const STEP_LABELS = {
  cart: "Cart",
  shipping: "Shipping",
  payment: "Payment",
  review: "Review",
  submitting: "Review",
  success: "Complete",
  error: "Review",
};

export function CheckoutWizard({ cartId }: { cartId: string }) {
  const [state, send] = useMachine(checkoutMachine, {
    input: { cartId },
  });

  const steps = ["cart", "shipping", "payment", "review"] as const;
  const currentStepIndex = steps.indexOf(state.value as any);

  return (
    <div className="max-w-2xl mx-auto">
      {/* Progress indicator */}
      <div className="flex gap-2 mb-8">
        {steps.map((step, i) => (
          <div
            key={step}
            className={`flex-1 h-1 rounded-full transition-colors ${
              i <= currentStepIndex ? "bg-blue-500" : "bg-gray-200"
            }`}
          />
        ))}
      </div>
      <p className="text-sm text-gray-500 mb-6">
        Step {Math.max(currentStepIndex + 1, 1)} of {steps.length}: {STEP_LABELS[state.value as keyof typeof STEP_LABELS]}
      </p>

      {/* Step components */}
      {state.matches("cart") && (
        <CartStep cartId={cartId} onNext={() => send({ type: "NEXT" })} />
      )}
      {state.matches("shipping") && (
        <ShippingStep
          onSubmit={(address) => {
            send({ type: "SET_SHIPPING", address });
            send({ type: "NEXT" });
          }}
          onBack={() => send({ type: "BACK" })}
        />
      )}
      {state.matches("payment") && (
        <PaymentStep
          onSubmit={(method) => {
            send({ type: "SET_PAYMENT", method });
            send({ type: "NEXT" });
          }}
          onBack={() => send({ type: "BACK" })}
        />
      )}
      {(state.matches("review") || state.matches("submitting") || state.matches("error")) && (
        <ReviewStep
          context={state.context}
          isSubmitting={state.matches("submitting")}
          error={state.context.error}
          onSubmit={() => send({ type: "SUBMIT" })}
          onRetry={() => send({ type: "RETRY" })}
          onBack={() => send({ type: "BACK" })}
        />
      )}
      {state.matches("success") && (
        <SuccessStep orderId={state.context.orderId!} />
      )}
    </div>
  );
}

---

Testing State Machines

// machines/checkout.machine.test.ts
import { createActor } from "xstate";
import { checkoutMachine } from "./checkout.machine";

describe("Checkout machine", () => {
  it("follows happy path cart → shipping → payment → review → success", async () => {
    const actor = createActor(checkoutMachine, {
      input: { cartId: "cart-123" },
    });
    actor.start();

    expect(actor.getSnapshot().value).toBe("cart");

    actor.send({ type: "NEXT" });
    expect(actor.getSnapshot().value).toBe("shipping");

    actor.send({ type: "SET_SHIPPING", address: { line1: "123 Main St", city: "NYC", zip: "10001" } });
    actor.send({ type: "NEXT" });
    expect(actor.getSnapshot().value).toBe("payment");

    actor.send({ type: "SET_PAYMENT", method: { type: "card", last4: "4242" } });
    actor.send({ type: "NEXT" });
    expect(actor.getSnapshot().value).toBe("review");

    // NEXT on payment without payment method should not advance
    actor.stop();
  });

  it("cannot advance past shipping without address", () => {
    const actor = createActor(checkoutMachine, {
      input: { cartId: "cart-123" },
    });
    actor.start();
    actor.send({ type: "NEXT" }); // → shipping
    actor.send({ type: "NEXT" }); // Should NOT advance without address

    expect(actor.getSnapshot().value).toBe("shipping"); // Still on shipping
  });

  it("allows retry after error", async () => {
    const actor = createActor(checkoutMachine, {
      input: { cartId: "bad-cart" }, // Will cause error
    });
    actor.start();

    // Fast-forward to error state
    // (In real test, mock the submitOrder actor to reject)
    // ...

    actor.send({ type: "RETRY" });
    expect(actor.getSnapshot().value).toBe("review");
  });
});

---

When to Use Each

---

Cost and Timeline

---

See Also

• React Optimistic Updates — Managing optimistic state alongside machine state
• React Testing Library Patterns — Testing wizard components
• SaaS Onboarding Checklist — Multi-step onboarding flow
• React Form Builder — Dynamic forms inside wizard steps

---

Working With Viprasol

We model complex React UI flows as finite state machines — checkout wizards, onboarding flows, multi-step forms, and document processing pipelines. Our team has shipped XState-powered flows that eliminated entire categories of "impossible state" bugs in production.

What we deliver:

• Flow analysis and state diagram before writing code
• useReducer state machine for simpler flows
• XState v5 with full TypeScript inference for complex flows
• State machine test suite with transition coverage
• UI components that render purely from machine state

Explore our web development services or contact us to model your complex UI flows.