useActionState

1The Problem It Solves

Handling a form submission that hits the network traditionally means wiring up pending, error, and result state by hand, and manually calling preventDefault before doing async work:

// Without useActionState: three separate pieces of state, wired by hand
function ContactForm() {
  const [pending, setPending] = useState(false);
  const [message, setMessage] = useState<string | null>(null);

  async function handleSubmit(e: React.FormEvent<HTMLFormElement>) {
    e.preventDefault();
    setPending(true);
    const formData = new FormData(e.currentTarget);
    const result = await submitContact(formData);
    setMessage(result);
    setPending(false);
  }

  return (
    <form onSubmit={handleSubmit}>
      <input name="email" />
      <button disabled={pending}>{pending ? "Sending..." : "Send"}</button>
      {message && <p>{message}</p>}
    </form>
  );
}

useActionState bundles "the latest result of an async action" and "whether it's currently in flight" into a single hook, and hands back a form-compatible action function that plugs directly into <form action={...}> — no manual preventDefault, no manual pending state.

2The Basic API

import { useActionState } from "react";

async function submitContact(previousState: string | null, formData: FormData) {
  await new Promise((resolve) => setTimeout(resolve, 1000)); // simulated network call
  const email = formData.get("email") as string;
  return `Thanks, we'll email you at ${email}!`;
}

function ContactForm() {
  const [message, formAction, isPending] = useActionState(submitContact, null);

  return (
    <form action={formAction}>
      <input name="email" type="email" />
      <button disabled={isPending}>{isPending ? "Sending..." : "Send"}</button>
      {message && <p>{message}</p>}
    </form>
  );
}

useActionState(actionFn, initialState) returns a 3-tuple: [state, formAction, isPending].

• state — whatever actionFn most recently returned (or initialState before the first submission).
• formAction — a wrapped version of actionFn to pass to <form action={...}> (or call directly).
• isPending — true while the action is in flight.

Crucially, actionFn itself takes the previous state as its first argument, followed by the form data — that's the shape React requires so it can thread state from one submission to the next.

3Why the Action Signature Takes previousState First

// The action's signature is ALWAYS (previousState, formData) => newState
async function voteAction(previousState: number, formData: FormData): Promise<number> {
  const delta = formData.get("direction") === "up" ? 1 : -1;
  return previousState + delta; // builds on the last committed result
}

function VoteWidget() {
  const [votes, formAction] = useActionState(voteAction, 0);
  return (
    <form action={formAction}>
      <button name="direction" value="up">Upvote ({votes})</button>
    </form>
  );
}

This mirrors useReducer's (state, action) => newState shape deliberately — useActionState is conceptually "a reducer whose action is a form submission and whose reducer function is allowed to be async." Each submission's result becomes the input to the next submission's previousState, letting an action accumulate — a running total, a growing list of errors, an incrementing counter — without any extra state variables.

4Handling Validation Errors Without Extra State

Because the action's return value is the hook's state, validation/error results flow through the same channel as success results — no separate error state needed:

interface FormResult {
  success: boolean;
  message: string;
}

async function submitEmail(_prev: FormResult | null, formData: FormData): Promise<FormResult> {
  const email = formData.get("email") as string;
  if (!email.includes("@")) {
    return { success: false, message: "Please enter a valid email." };
  }
  await sendEmail(email);
  return { success: true, message: "Sent!" };
}

function EmailForm() {
  const [result, formAction, isPending] = useActionState(submitEmail, null);
  return (
    <form action={formAction}>
      <input name="email" />
      <button disabled={isPending}>Submit</button>
      {result && (
        <p style={{ color: result.success ? "green" : "red" }}>{result.message}</p>
      )}
    </form>
  );
}

5Calling the Action Outside a <form>

formAction isn't restricted to <form action={...}> — it can be called directly (e.g. from a button's onClick, bound with extra arguments), which is useful when the "form" is really just a single button triggering a server mutation:

async function deleteItemAction(_prev: string | null, itemId: string) {
  await deleteItem(itemId);
  return `Deleted item ${itemId}`;
}

function DeleteButton({ itemId }: { itemId: string }) {
  const [status, deleteAction, isPending] = useActionState(deleteItemAction, null);
  return (
    <button onClick={() => deleteAction(itemId)} disabled={isPending}>
      {isPending ? "Deleting..." : "Delete"}
    </button>
  );
}

Note this variant's action takes whatever argument the caller passes as its second parameter — it need not be a FormData at all; FormData only appears automatically when formAction is wired to a real <form action={...}>.

6Composed With useFormStatus

A component nested inside the <form> can read the same in-flight status independently via useFormStatus (from react-dom), without isPending being threaded down as a prop — see the useFormStatus topic for the full picture of how the two hooks share the same underlying pending-transition tracking.

⚠️ Common Pitfalls

1. Forgetting the action's first parameter is previousState, not the form data — the signature is always (previousState, formData) => newState; putting form data first silently breaks the state-threading contract.
2. Mutating previousState in place instead of returning a new value — exactly like useReducer, the action should be treated as pure with respect to its inputs, returning a new state value rather than mutating the old one.
3. Manually managing a separate pending/error state alongside useActionState — defeats the purpose; let the action's return value carry error/result info, and read isPending directly from the hook.
4. Calling formAction and expecting a return value synchronously — the action runs as a transition; its result lands in state on a subsequent render, not as this call's return value.
5. Assuming useActionState requires a real <form> — formAction can be called directly (e.g., from onClick) with any argument shape; the FormData convention only applies when wired to <form action={...}>.

📋 Quick Reference

const [state, formAction, isPending] = useActionState(actionFn, initialState)

actionFn: (previousState, formData) => newState   → newState may be a Promise
formAction  → pass to <form action={formAction}> OR call directly with any arg
isPending   → true while the action's transition is in flight

Error handling: return an error shape from actionFn instead of throwing;
                no separate error state needed — it's just part of `state`.

🎤 Interview Q&A

🛠️ Practice exercises

Each exercise is a file in this topic folder. Code exercises are self-checking: run them and make the checks pass.

✅ Check yourself

Source: react_useactionstate_theory.md · generated by tools/build_lessons.py