Progressive Forms with Actions

Disable JavaScript in your browser, open a signup page, and submit it. In most SPAs you get a silent no-op; in a Next.js form bound to a server action you get a created account. That is progressive enhancement in one demo, and it works because the form's action is a server function whose identifier is already embedded in the HTML.

// app/todos/NewTodo.tsx  — no 'use client' needed for this shape
import { addTodo } from './actions';

export function NewTodo() {
  return (
    <form action={addTodo}>
      <input name="title" placeholder="What needs doing?" required />
      <input name="due" type="date" />
      <button type="submit">Add</button>
    </form>
  );
}

With JavaScript, React intercepts the submit: it collects the fields into FormData, serializes a request carrying the action's build-generated ID, runs addTodo on the server, and streams back the re-rendered route — no page navigation, no full reload, no fetch written by you.

Without JavaScript, nothing is intercepted, so the browser does what browsers have done since 1995: POST the form to the current URL with the field values as application/x-www-form-urlencoded. Next.js has already placed hidden inputs in the markup ($ACTION_ID_…) identifying which action to run, so the server executes the same addTodo, and — because there is no client router to patch the DOM — the response is a full document containing the updated list. Both paths converge on one function and one re-render; the only difference is whether the result arrives as an RSC payload or as a new HTML document.

That convergence sets real constraints on how you write the form:

The interaction with redirects is a sharp edge worth knowing: redirect() throws a special control-flow error, so call it after your mutation and do not wrap it in a try/catch that swallows it (catch and rethrow, or narrow the catch to the mutation itself). An action that catches everything will silently turn a redirect into a normal return, and the user stays on the form.

What you give up versus a fetch to an API route is also concrete: no streaming request body, no custom headers, no GET semantics, and the response is a rendered tree rather than data you manipulate. What you gain is smaller code, framework-owned revalidation, an identifier rather than a hand-maintained route, and a form that works before hydration. The next chapter is about the one thing the plain form cannot do by itself — telling the user what happened.

The bare form works, but "worked" is invisible: the todo appears in the list only because the route re-rendered, and a failed action (name too long, duplicate slug, DB down) gives the user nothing to read. The action already returns a value — you need a way to hand that value back to the form's UI, and that is what the form-state hook does.

'use client';
import { useActionState } from 'react';
import { addTodo } from './actions';

type State = { message?: string; errors?: Record<string, string> } | null;

export function NewTodo() {
  const [state, formAction, isPending] = useActionState<State, FormData>(
    addTodo,          // the server action
    null,             // initial state
  );

  return (
    <form action={formAction}>
      <input name="title" aria-invalid={!!state?.errors?.title} />
      {state?.errors?.title && (
        <p role="alert" className="text-red-600">{state.errors.title}</p>
      )}
      <button type="submit" disabled={isPending}>
        {isPending ? 'Adding…' : 'Add'}
      </button>
    </form>
  );
}

The hook returns a three-tuple: [state, action, isPending]. The action it hands back is a bound version you put in <form action=...>, state is whatever your server action returned on the last invocation, and isPending covers the button label. On the server side the action's signature changes shape — its first argument is the previous state, the second is FormData:

'use server';
export async function addTodo(prev: State, formData: FormData): Promise<State> {
  const title = String(formData.get('title') ?? '');
  if (title.length < 3) return { errors: { title: 'Too short' } };
  await db.todo.create({ data: { title } });
  revalidatePath('/todos');
  return { message: 'Added' };
}

Naming history matters here, because older code and newer docs disagree. What was useFormState (imported from react-dom, Next 14 era) is now useActionState (from react, React 19 / Next 15) — same tuple, same semantics, plus the pending flag folded in. If you are reading a tutorial that says useFormState, translate it mentally; the migration is a rename and an import change, and the return-value channel is identical.

Two design consequences follow. First, the return value is the only out-of-band channel — there is no imperative setState after the call, so structure returns as data: { errors: {...} } for field problems, { ok: true, id } for success, and let the template branch. Second, state is per form instance: two NewTodo forms each hold their own last result, and a key change (new todo id, route change) remounts the form and clears it — which is the standard trick for "reset the error message" when the action succeeded.

Note what the tuple's second element really is: formAction is not your raw import, it is a bound wrapper the hook returns, which knows how to dispatch to the server and pair the result with the current state. Passing the imported action directly into <form action={...}> still works (that is the previous chapter's version) — you just have no state to read afterwards. The two forms coexist in one codebase: bare action for simple submits, useActionState the moment the template needs to display a result.

Progressive enhancement still holds: with JS off, useActionState never hydrates, the browser posts natively, and the server's full-document response re-renders the form with the same state object passed through the action, so error messages appear in the HTML too. The hook enhances presentation (pending flag, no navigation) rather than adding capability. What it deliberately does not solve is what happens to the fields themselves — the reset semantics, covered next.

One common surprise when moving from an API-route architecture: after the action returns, you no longer write router.push('/success') or setSubmitting(false) — the framework owns both the pending window and the re-render. The code you delete in this migration (fetch, loading flag, refetch, refetch-after-error) is the argument for the pattern; the code you must now write carefully is the state shape returned by the action, since it is the only thing standing between "the server rejected this" and "the user understands why".

The user types a title, submits, sees "Added" — and the input is empty again without anyone writing setFormData(''). React resets an uncontrolled form automatically after its action completes successfully. That default is doing you a favor you should understand, because three bugs sit right next to it.

Bug one: the field that won't clear. If the input is controlled (value={title} onChange={...}), React's automatic reset sets the DOM value but your state still holds the old string, so the input snaps back to the typed text. The mismatch looks like "the reset is broken"; the actual fix is one of: make the input uncontrolled (preferred for forms bound to actions), or key the form after success so the component remounts with fresh state:

<form key={state?.id ?? 'idle'} action={formAction}> ... </form>

Bug two: the error that survives success. useActionState keeps the last result until the next submission, so a stale "Too short" can sit beside a now-valid list. Clear it where the source of truth changes — return a fresh state object from the action (you already do), or remount with key as above. Note the flip side, which is the useful behavior: an error stays visible until the user tries again, so a failed submit never silently erases its explanation.

Bug three: losing input on failure. Because React only clears fields after a successful action, a returned validation error leaves everything the user typed intact — which is exactly what you want when they must fix one field. If you find yourself re-populating the form from server data after an error, something in your flow is treating a normal validation failure like an exception; return the errors instead of throwing and the fields take care of themselves.

Validation itself has two layers, and the no-JS constraint decides how much each one matters:

layer 1: HTML attributes  (required, minLength, type="email", pattern)
         runs with JS off; fast, coarse, spoofable via curl

layer 2: schema parse inside the action (zod, valibot)
         always runs; authoritative; returns structured field errors

Layer one is a courtesy — better UX, fewer pointless round trips. Layer two is the contract: any client can POST directly with $ACTION_ID filled in, so an action that trusts required alone is an unvalidated endpoint. The full schema pattern (parse FormData, map issue paths to field keys, return them for inline display) is Validating Action Input; the shape that makes it render is established right here.

Note how the two layers compose on a no-JS submit: the browser enforces required natively and never posts the empty field, but a curl that does post it gets the server-side error rendered back into the re-rendered form — the same error object, delivered through a document instead of a hook. That symmetry is the test of a well-designed action: ask whether each failure message still reaches the user with JavaScript disabled, and any that does not is a message you wired to client-only state.

Finally, the pending state: isPending disables the submit button, and disabling it is your defense against double submission — a second click before the first response would post twice and create two todos. Keep the button disabled, but do not rely on it as idempotency: networks retry, users mash Enter before hydration, and a well-written action makes duplicate creation impossible (a unique constraint, or a client-generated id in the form). The form-level guard improves UX; the data-level guarantee prevents the duplicate.