React Reference ยท react-dom Resource and Form APIs
useFormStatus in forms
Practical patterns for useFormStatus from react-dom: a reusable submit button, disabling a fieldset, showing submitted data while pending, and the parent trap.
This page collects the patterns that grow around useFormStatus. The hook itself is small: called inside a component that is rendered within a <form>, it returns { pending, data, method, action } for the closest parent form. The interesting part is how you arrange components around it: a shared submit button, a block of fields that locks while saving, a "saving..." note that quotes what is being saved.
All of them rely on the same fact. A <form action={fn}> marks itself pending while fn runs (including an async function awaiting a promise), and every child that reads the hook re-renders when that flag changes. Nothing needs to be passed down as props.
import { useFormStatus } from 'react-dom'; function SubmitButton({ children }) { const { pending } = useFormStatus(); return <button disabled={pending}>{pending ? 'Working...' : children}</button>; }
Try it
Press Save. For one second the button is disabled and reads "Saving...", the note quotes the title from data, and then the title joins the list and the form returns to its idle look.
While the action runs the child reports pending = true, method = get, but the component that renders the <form> itself still says false: it is not inside any form, so it has nothing to read. When idle, method is null.
Syntax
const { pending, data, method, action } = useFormStatus();
function useFormStatus(): { pending: boolean; data: FormData | null; method: 'get' | 'post' | null; action: string | ((formData: FormData) => void | Promise<void>) | null; };
| Field | Description |
|---|---|
pending |
true while the parent form's action is running. |
data |
The FormData being submitted, or null when idle. Good for "Saving X..." messages and optimistic hints. |
method |
The form's HTTP method as a lowercase string. With a function action it reads "get" unless you set method. null when idle. |
action |
The function or URL passed as the form's action; null when idle. |
Returns: a status object; all fields are inert (pending: false, the rest null) when there is no parent form.
Errors / edge cases: the hook does not throw outside a form, it just reports "not pending" forever, which is the usual symptom of calling it in the wrong component.
Usage notes
- Put the hook in a child. The component that renders
<form>cannot read its own form's status. Move the button (or any status display) into a separate component, as the second example shows. - Lock a block of fields. A small
Fieldscomponent that readspendingand renders<fieldset disabled={pending}>stops edits during a save. Disabled controls are not in the next submission, but the one in flight already has itsFormDatasnapshot. - Disable, don't hide. Swapping the button for a spinner shifts the layout; a disabled button with changed text does not.
- Only function actions count. Forms handled by
onSubmitwithpreventDefaultnever become pending; track those withuseTransitionor your own state. - Pending covers the whole action. If it awaits a request, pending stays
trueuntil the promise settles, success or failure. - Show results with something else.
useFormStatusreports progress, not outcome. For a message or error useuseActionState; for instant feedback useuseOptimistic. - Several forms: each component reads its own nearest parent form, so one
SubmitButtoncan be reused in every form. - Accessibility: a pending submit button should still read sensibly to screen readers. Keep the visible text and consider
aria-busyon the form.