React 19 Actions — useActionState · useFormStatus

useState → Actions: async form state in one hook

Before React 19, a single form submission meant hand-rolling 3-4 pieces: useState for the fields, useState for pending, useState for error, a try/catch/finally around the fetch, and manual disable/enable of the submit button. React 19 collapses that into Actions — async functions passed to <form action> or wrapped with startTransition, plus three hooks that read the resulting lifecycle.

hook	signature	role
`useActionState`	`[state, formAction, isPending] = useActionState(reducerAction, init)`	"useReducer for side effects" — `reducerAction` may be async, may POST. Returns the result + a dispatcher + a pending flag.
`useFormStatus`	`{ pending } = useFormStatus()` (child of `<form>`)	Reads the parent form's pending state from React's internal context — a deep `<SubmitButton/>` needs zero props.
`useOptimistic`	`[optimisticValue, addOptimistic] = useOptimistic(realValue)`	Layers a predicted value on top during the pending window; React auto-reverts to `realValue` when the action resolves.

API probe (runtime): useActionState=… · useFormStatus=… · useOptimistic=…. This page simulates the action lifecycle with useReducer (idle→pending→success) and the optimistic overlay with useState — the pattern is identical; the simulation just sidesteps the <form action> React-internal context that is fragile inside an eval sandbox. See the guide for the exact native APIs.

1 · the action state machine (edit me)

// ============================================================================
// React 19 Actions — SIMULATED via useReducer + useState.
// The reducer models the form action lifecycle that useActionState automates:
//   idle  --submit-->  pending  --success-->  success
//                            \---error----->  error
// The optimistic overlay models what useOptimistic gives you for free: an
// instant predicted value that is discarded once the real result lands.
// ============================================================================

// --- SIMULATED useActionState: a pure reducer for the action lifecycle --------
function actionReducer(state, action) {
  switch (action.type) {
    case 'submit':  return { status: 'pending', name: action.name, error: null };
    case 'success': return { status: 'success', name: action.name, error: null };
    case 'error':   return { status: 'error',   name: action.name, error: action.error };
    case 'reset':   return { status: 'idle',    name: '', error: null };
    default:        return state;
  }
}

// --- SIMULATED useFormStatus: a child that "just knows" the form is pending ---
// Real useFormStatus reads the parent <form action> context. We simulate it by
// threading `pending` through a tiny Context — the point is zero prop-drilling
// into the deep <SubmitButton/> tree.
var FormStatusCtx = React.createContext({ pending: false });

function SubmitButton() {
  var status = React.useContext(FormStatusCtx); // ← the useFormStatus stand-in
  return (
    <button
      data-testid="submit"
      type="submit"
      disabled={status.pending}
      className={"px-4 py-2 rounded font-bold text-sm " +
        (status.pending
          ? "bg-[#30363d] text-[#8b949e] cursor-not-allowed"
          : "bg-[#61dafb] text-[#0d1117] hover:opacity-80")}
    >
      {status.pending ? 'Submitting…' : 'Submit'}
    </button>
  );
}

function ActionsDemo() {
  // (1) useActionState, simulated — the action lifecycle lives in ONE reducer.
  var reduced = React.useReducer(actionReducer, { status: 'idle', name: '', error: null });
  var formState = reduced[0];
  var dispatch  = reduced[1];
  var isPending = formState.status === 'pending';

  // (2) useOptimistic, simulated — a predicted name shown only during pending.
  var optState = React.useState('');
  var optimisticName = optState[0];
  var setOptimisticName = optState[1];

  // What the UI shows: optimistic overlay during pending, real result otherwise.
  var displayedName = isPending ? optimisticName : formState.name;

  function handleSubmit(e) {
    if (e && e.preventDefault) e.preventDefault();
    var input = document.querySelector('[data-testid="name-input"]');
    var name = (input && input.value.trim()) ? input.value.trim() : 'Anonymous';

    setOptimisticName(name + ' ⚡');           // optimistic: predicted value, NOW
    dispatch({ type: 'submit', name: name });  // lifecycle → pending

    // Simulated async reducerAction (the side effect useActionState allows).
    setTimeout(function () {
      dispatch({ type: 'success', name: name }); // reconcile with the real result
    }, 600);
  }

  function handleReset() {
    dispatch({ type: 'reset' });
    setOptimisticName('');
    var input = document.querySelector('[data-testid="name-input"]');
    if (input) input.value = '';
  }

  var statusColor =
    formState.status === 'success' ? 'text-[#2ecc71]' :
    formState.status === 'error'   ? 'text-[#e74c3c]' :
    formState.status === 'pending' ? 'text-[#f1c40f]' :
                                     'text-[#8b949e]';

  return (
    <div className="max-w-md mx-auto p-5 bg-[#161b22] rounded-xl border border-[#30363d]">
      <h2 className="text-lg font-bold text-[#61dafb] mb-1">Profile name</h2>
      <p className="text-xs text-[#8b949e] mb-4">
        status: <span data-testid="status" className={statusColor + " font-bold"}>{formState.status}</span>
      </p>

      {/*
        In real React 19 you'd write <form action={dispatch}> and React would
        wrap the submission in a Transition for you. We simulate with onSubmit so
        the demo is bulletproof inside the eval sandbox.
      */}
      <FormStatusCtx.Provider value={{ pending: isPending }}>
        <form data-testid="form" onSubmit={handleSubmit} className="flex gap-2 mb-4">
          <input
            data-testid="name-input"
            className="flex-1 px-3 py-2 bg-[#0d1117] border border-[#30363d] rounded text-[#e6edf3] text-sm outline-none focus:border-[#61dafb]"
            placeholder="Enter a display name…"
          />
          <SubmitButton />
        </form>
      </FormStatusCtx.Provider>

      <div data-testid="result-panel" className="p-3 bg-[#0d1117] rounded border border-[#30363d]">
        <p className="text-xs text-[#8b949e] m-0">committed name:</p>
        <p data-testid="committed" className="text-base text-[#e6edf3] mt-1 mb-0 break-words">
          {displayedName || '(none)'}
        </p>
        {isPending ? (
          <p data-testid="optimistic-flag" className="text-xs text-[#f1c40f] mt-2 mb-0">
            ⚡ optimistic value shown — will reconcile on resolve
          </p>
        ) : null}
      </div>

      <button
        data-testid="reset"
        onClick={handleReset}
        className="mt-3 text-xs text-[#8b949e] hover:text-[#e6edf3] underline"
      >
        reset
      </button>
    </div>
  );
}

createRoot(document.getElementById('root')).render(<ActionsDemo/>);

2 · Babel compiles JSX → element tree

<ActionsDemo/> becomes React.createElement(ActionsDemo). Each dispatch({{type:'submit'}}) runs the reducer, React re-renders with status:'pending'; the setTimeout then dispatches 'success' and the optimistic overlay is discarded.

// (hit "compile & render" to see Babel's output)

3 · live React (the action lifecycle, proven)

The gold-check drives this automatically: asserts status:"idle" → types a name + clicks Submit → asserts status:"pending" (action started, optimistic value shown) → waits for the simulated async → asserts status:"success" with the committed name. That proves the idle→pending→success state machine and optimistic reconciliation end-to-end.

status: — · gold: idle → pending → success + committed name

useActionState vs useReducer

aspect	`useReducer`	`useActionState`
reducer purity	MUST be pure — no `fetch`, no timers	`reducerAction` MAY be async & run side effects
return value	`[state, dispatch]` (2 items)	`[state, dispatchAction, isPending]` (3 items)
dispatch contract	call anywhere	must run inside a `startTransition` or an Action prop
queuing	batched, parallel reducer calls	sequential — each call waits for the previous result
built-in pending flag	no — you wire `isPending` yourself	yes — third return value
best for	UI state machines (todos, steppers)	form submissions, mutations, server actions

intent → pattern

intent	pattern	why
submit a form, track pending	`useActionState(asyncAction, init)` + pass `dispatchAction` to `<form action>`	React wraps the submit in a Transition; `isPending` is free
show predicted value while waiting	`useOptimistic(real)` + `addOptimistic(pred)` inside the action	instant feedback; React auto-reverts to `real` on resolve
deep submit button knows it's submitting	`useFormStatus()` in a child of `<form>`	no prop-drilling — reads React's form context
handle validation / server errors	return `{error}` state from `reducerAction`	known errors → UI; unknown throws → nearest Error Boundary