Form actions and useActionState

A form action is a function that runs with FormData on submit — <form action={fn}> replaces onSubmit + preventDefault + reading each field. React calls your function with the form’s FormData, so you read fields by name, not by wiring controlled state to every input. There’s no event to prevent; submission is the action call.

function ContactForm() {
  async function submit(formData: FormData) {
    const email = formData.get("email") as string;
    await sendMessage(email, formData.get("body") as string);
  }
  return (
    <form action={submit}>
      <input name="email" type="email" />
      <textarea name="body" />
      <button>Send</button>
    </form>
  );
}

The inputs are uncontrolled — name is the contract. You only reach for useState per field when you genuinely need to render off keystrokes (live validation, a character counter), not just to collect a value at submit.

useActionState wraps the action and hands back [state, dispatch, isPending] — that’s your result, error, and pending flag without any of them being hand-rolled. You give it a reducer-shaped function (prevState, formData) => nextState and an initial state. React runs it on submit, tracks the pending transition, and stores whatever you return as the new state. Validation errors are just a returned value, not a thrown exception you have to catch and stash.

type State = { ok: boolean; error?: string };

async function submitContact(_prev: State, formData: FormData): Promise<State> {
  const email = String(formData.get("email") ?? "");
  if (!email.includes("@")) return { ok: false, error: "Enter a valid email" };
  await sendMessage(email, String(formData.get("body") ?? ""));
  return { ok: true };
}

function ContactForm() {
  const [state, action, isPending] = useActionState(submitContact, { ok: false });
  return (
    <form action={action}>
      <input name="email" type="email" />
      <textarea name="body" />
      {state.error && <p role="alert">{state.error}</p>}
      <button disabled={isPending}>{isPending ? "Sending…" : "Send"}</button>
    </form>
  );
}

Notice what’s gone: no const [isSubmitting, setIsSubmitting], no try/catch, no finally to reset flags. The pending flag comes from the transition React is already managing; the error is just the state you returned.

useFormStatus reads the enclosing form’s submit state from inside a child — so a shared <SubmitButton> knows it’s pending with zero props. The catch that trips people: it must be called in a component rendered inside the <form>, not in the component that renders the form. That boundary is the whole point — it lets you ship a reusable submit button that any form can drop in, and it lights up automatically.

import { useFormStatus } from "react-dom";

function SubmitButton({ children }: { children: React.ReactNode }) {
  const { pending } = useFormStatus(); // reads the parent <form>, not props
  return <button disabled={pending}>{pending ? "Submitting…" : children}</button>;
}

// any form gets the pending button for free
<form action={action}>
  <input name="email" />
  <SubmitButton>Save</SubmitButton>
</form>

useFormStatus is for the button’s local feedback; useActionState’s isPending is for the form-owner’s logic (disabling a fieldset, showing a result). Use whichever sits where you need the signal — don’t drill isPending down when useFormStatus reads it natively.

The same action runs on the client or as a server action — but a server action is a public HTTP endpoint, so it must validate its own input. Mark a function "use server" and <form action={serverAction}> posts the FormData to the server; the form works before hydration, and progressive enhancement is real. The senior trap: client-side validation (the type="email", the disabled button) is UX, not a security boundary. Anyone can POST arbitrary FormData straight to that action, so it must re-validate and authorize on the server, as if the client never ran.

// app/actions.ts
"use server";
import { z } from "zod";

const Contact = z.object({ email: z.string().email(), body: z.string().min(1).max(2000) });

export async function submitContact(_prev: State, formData: FormData): Promise<State> {
  const parsed = Contact.safeParse({ email: formData.get("email"), body: formData.get("body") });
  if (!parsed.success) return { ok: false, error: "Invalid input" }; // server is the real gate
  await requireSession();                 // authz here, never trust the client
  await db.messages.insert(parsed.data);
  return { ok: true };
}

The action’s signature is identical to the client version — that’s the unification. What changes is that the boundary moved across the network, and everything on the far side treats its input as hostile.