useFormStatus

1The Problem It Solves

A reusable <SubmitButton> component needs to disable itself and show a spinner while the form it lives inside is submitting — without every parent that renders a <form> having to manually track a pending boolean and pass it down as a prop.

// Without useFormStatus: every form's parent must track and pass pending manually
function ContactForm() {
  const [pending, setPending] = useState(false);
  async function action(formData: FormData) {
    setPending(true);
    await submitContact(formData);
    setPending(false);
  }
  return (
    <form action={action}>
      <input name="email" />
      <SubmitButton pending={pending} /> {/* has to be threaded through by hand */}
    </form>
  );
}

useFormStatus lets SubmitButton read its enclosing form's pending status directly, with zero props — the same <SubmitButton> works correctly inside ContactForm, SignupForm, or any other form, automatically tracking whichever form it happens to be rendered inside.

2Signature

import { useFormStatus } from "react-dom"; // NOT "react" — this hook lives in react-dom

function SubmitButton() {
  const { pending, data, method, action } = useFormStatus();
  return <button disabled={pending}>{pending ? "Submitting..." : "Submit"}</button>;
}

3Must Be Called in a Child of the <form>, Not the Component Rendering It

// BROKEN: calling useFormStatus() in the SAME component that renders <form>
function ContactForm() {
  const { pending } = useFormStatus(); // ALWAYS pending: false — no ancestor form exists yet
  return (
    <form action={submitContact}>
      <button disabled={pending}>Submit</button>
    </form>
  );
}

// FIXED: extract a child component rendered INSIDE the <form>
function SubmitButton() {
  const { pending } = useFormStatus(); // correctly reads the ancestor <form>'s live status
  return <button disabled={pending}>Submit</button>;
}

function ContactForm() {
  return (
    <form action={submitContact}>
      <input name="email" />
      <SubmitButton />
    </form>
  );
}

The rule: useFormStatus reports the status of the nearest ancestor <form>. The component that renders the <form> tag is not inside its own form's subtree — the form is its descendant, not its ancestor — so calling the hook there always returns the inactive default.

4Composed with useActionState

useFormStatus and useActionState (previous topic) are commonly used together: useActionState manages the form's submission result and its own pending flag at the call site that owns the action, while useFormStatus lets any nested component independently read that same pending status without the action's owner passing it down manually.

import { useActionState } from "react";
import { useFormStatus } from "react-dom";

async function submitContact(_prevState: string | null, formData: FormData) {
  await new Promise((resolve) => setTimeout(resolve, 1000)); // simulated network delay
  return `Thanks, ${formData.get("email")}!`;
}

function SubmitButton() {
  const { pending } = useFormStatus(); // independent read — no prop from ContactForm needed
  return <button disabled={pending}>{pending ? "Sending..." : "Send"}</button>;
}

function ContactForm() {
  const [message, formAction] = useActionState(submitContact, null);
  return (
    <form action={formAction}>
      <input name="email" />
      <SubmitButton />
      {message && <p>{message}</p>}
    </form>
  );
}

SubmitButton never receives pending as a prop — it independently subscribes to the enclosing <form>'s status via useFormStatus, and React keeps both useActionState's pending flag and useFormStatus's pending flag in sync with the same underlying form-action transition.

5Reading data, method, and action

function SubmitButton() {
  const { pending, data } = useFormStatus();
  const submittingEmail = data?.get("email");
  return (
    <button disabled={pending}>
      {pending ? `Submitting: ${submittingEmail}...` : "Submit"}
    </button>
  );
}

Reading data directly off useFormStatus() lets a child component reflect exactly what's in flight — no need to duplicate that value into separate state just so a nested component can display it.

⚠️ Common Pitfalls

1. Calling useFormStatus in the same component that renders the <form> — always returns the inactive default; extract a child component and call the hook there instead.
2. Importing from "react" instead of "react-dom" — useFormStatus is a React DOM hook, not a core React hook.
3. Assuming it tracks any nearby form — it specifically reports the nearest ancestor <form>; separate sibling forms each need their own descendant component independently calling the hook.
4. Confusing pending with general async loading state — it reflects only the enclosing form's action transition, not arbitrary async work happening elsewhere in the app.
5. Expecting data to be populated when not pending — data is null outside of an in-flight submission; guard with optional chaining (data?.get(...)).

📋 Quick Reference

import { useFormStatus } from "react-dom";     → note: react-dom, not react
const { pending, data, method, action } = useFormStatus();
pending  → boolean, true while the ancestor form's action is in flight
data     → FormData | null, the in-flight submission's data
method   → "get" | "post"
action   → the form's action reference

Rule: must be called in a CHILD of the <form>, never the component rendering the <form> itself.

🎤 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_useformstatus_theory.md · generated by tools/build_lessons.py