Chapter 104: useFormStatus

Core Idea

useFormStatus() lets a component nested inside a <form> read that form's pending/submission status without any prop drilling — designed specifically for reusable submit-button-style components that need to know "is my enclosing form currently submitting" without the form passing that state down explicitly.

Key Concepts

• Signature: const { pending, data, method, action } = useFormStatus() — must be called from a component rendered inside a <form> (a descendant, not the form component itself) to pick up that form's status.
• pending: true while the enclosing form's action (Ch 97) is in flight — the main value most components read, typically to disable a submit button or show a spinner.
• data/method/action: expose the in-flight submission's FormData, HTTP method, and action reference, letting a status-reading component render something more specific than a generic spinner (e.g. showing which data was submitted).
• No status outside a form: calling it in a component that isn't nested inside any <form> returns a default/inactive status object (pending: false, etc.) rather than throwing — but the intended use is always as a descendant of a form using the function-action pattern.
• The whole point is decoupling: a generic <SubmitButton> component can be written once, used inside any form, and automatically reflect that form's pending state — without the form needing to explicitly pass an isSubmitting prop down to it.

Code Examples

function SubmitButton() {
  const { pending } = useFormStatus();
  return <button disabled={pending}>{pending ? 'Submitting...' : 'Submit'}</button>;
}

// Usage: <form action={submitAction}><SubmitButton /></form>

• What it demonstrates: a reusable SubmitButton automatically disabling itself while its enclosing form is submitting, without the form passing any prop down to it.

Key Takeaways

1. Only works when nested inside a <form> — calling it in the form component itself, or a sibling outside the form, won't pick up that form's status.
2. Its main value is eliminating prop-drilling for pending state to deeply nested form-status-aware components.
3. Pairs naturally with the function-action form pattern (Ch 97) and useActionState (Ch 48) — it's reading the same underlying pending signal from a different position in the tree.

Connects To

• Ch 97 (<form>): the function-action submission this Hook reports status for.
• Ch 48 (useActionState): the reducer-driven alternative for reading pending state from the form's own component instead of a descendant.