React Reference ยท Performance and Concurrency Hooks
React useFormStatus hook
Reference for React useFormStatus from react-dom: read pending, data, method and action of the parent form from a child, such as a submit button.
useFormStatus tells a component what its parent <form> is doing right now. It is exported from react-dom (not react) and returns an object with pending, data, method and action. The usual use is a reusable submit button that disables itself while the form's action runs, without receiving a pending prop.
The hook reads the status of the parent form. It must be called in a component that is rendered inside a <form>, not in the component that renders the form.
import { useFormStatus } from 'react-dom'; const { pending } = useFormStatus();
Try it
Syntax
const { pending, data, method, action } = useFormStatus();
| Field | Description |
|---|---|
pending |
true while the parent form's submission is in progress, else false. |
data |
A FormData of the submitted fields while pending; null otherwise. |
method |
'get' or 'post' (from the form's method; defaults to 'get'). |
action |
The function or URL the form was submitted to; null when not pending. |
Returns: an object with those four fields. When there is no parent form, pending is always false and the rest are null.
Usage notes
- Call it below the form. Writing
const { pending } = useFormStatus()in the same component that renders<form>never reports pending. Extract a child likeSubmitButton. - Only
actionsubmissions count. It tracks forms that use a function (or Server Function) inaction. A manualonSubmitwithpreventDefaultdoes not setpending. - Import from
react-dom.import { useFormStatus } from 'react-dom'. Importing fromreactfails. - Nearest form only. If forms are nested through portals, the closest parent form wins.
- Good for disabling inputs too: a
<fieldset disabled={pending}>wrapper component works the same way. - Pending ends with the action. If the action returns a promise,
pendingstaystrueuntil it settles. - Use
useActionStatefor results.useFormStatusreports progress only, not return values; seeuseActionState.