Form actions and useActionState: mutations as a first-class React primitive

The primitive: a form whose action is a function

React 19 extends the HTML action attribute: instead of a URL, you pass a function. When the form submits, React prevents the default navigation, builds a FormData from the form’s named fields, and calls your function with it inside a transition — so the UI stays responsive while the async work runs, and React tracks its pending state for you. After the action resolves, React resets uncontrolled fields automatically (the post-submit clearing you used to write by hand). The fields arrive via name attributes, which quietly rehabilitates the uncontrolled style from lesson one: with actions, most form fields need no per-keystroke state at all.

useActionState is the state half of the primitive. You give it a reducer-shaped async function — previous state in, FormData in, new state out — plus the initial state, and it returns three things: the current state, a wrapped action to put on the form, and isPending.

async function subscribe(prevState, formData) {
  const email = formData.get("email");
  const parsed = emailSchema.safeParse(email);
  if (!parsed.success) {
    return { ok: false, error: "Enter a valid email", email };
  }
  const res = await api.subscribe(parsed.data);
  if (!res.ok) {
    return { ok: false, error: "Try again in a minute", email };
  }
  return { ok: true, error: null, email: "" };
}

function SignupForm() {
  const [state, formAction, isPending] = useActionState(subscribe, {
    ok: false,
    error: null,
    email: "",
  });

  return (
    <form action={formAction}>
      <input name="email" defaultValue={state.email} />
      <button disabled={isPending}>
        {isPending ? "Subscribing…" : "Subscribe"}
      </button>
      {state.error ? <p role="alert">{state.error}</p> : null}
    </form>
  );
}

Read the shape carefully: the action is a reducer over submissions. Each submit takes the previous state and produces the next — which is why returning the rejected email back in state matters: on a server-rendered failure the input can be re-seeded instead of wiped. Sequential submissions queue: if the user submits twice, the second action waits for the first, each receiving the latest state — no interleaved writes.

isPending and useFormStatus: two scopes of pending

isPending from useActionState tells you this action is in flight — use it where the form’s owner lives. useFormStatus answers a different question from a different place: called inside a component rendered under a form, it returns the pending state (plus the in-flight FormData) of the nearest enclosing form — like a context provided by the form element itself. That makes a SubmitButton component reusable across every form in the codebase without prop-drilling pending flags:

function SubmitButton({ children }) {
  const { pending } = useFormStatus();
  return <button disabled={pending}>{pending ? "Working…" : children}</button>;
}

The classic failure: calling useFormStatus in the same component that renders the <form>. It reads the status of a parent form, and there is none — pending is forever false, the button never disables, and nothing errors. The hook must live in a child of the form.

Progressive enhancement: the form that works before React does

Here is the part that changes architecture. With framework-provided server functions (a function marked "use server" passed to action), the framework serializes a reference to that function into the HTML. If the user submits before hydration — the Black Friday window — the browser performs a plain native form POST to the server, the framework routes it to the same function, and the page re-renders with the result. No JavaScript required on the client. After hydration, the same form upgrades: submission becomes the in-place transition with isPending, no navigation, fields preserved. useActionState participates too — its optional third argument, permalink, tells the no-JS POST which URL to target so the round-trip lands on the right page.

This is the unification the unit has been building toward: client mutation and server mutation are the same declaration. The action function is the single place where the mutation lives — validation (the shared zod schema from the previous lesson slots in verbatim), the write, and the next state. Whether it executes as a local async call or as a serialized server roundtrip is a deployment detail, not an architectural fork. The discipline it demands: model the form so it could work without JS — named fields, state returned rather than imperatively toasted — and the enhanced version inherits correctness from the degraded one, never the reverse.