Skip to content
Tutorials Center
My learning

Topics

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.

JSX
import { useFormStatus } from 'react-dom';

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

Try it

A reusable pending submit button

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.

The parent trap: same component versus child

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

JSX
const { pending, data, method, action } = useFormStatus();
TypeScript
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 Fields component that reads pending and renders <fieldset disabled={pending}> stops edits during a save. Disabled controls are not in the next submission, but the one in flight already has its FormData snapshot.
  • 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 onSubmit with preventDefault never become pending; track those with useTransition or your own state.
  • Pending covers the whole action. If it awaits a request, pending stays true until the promise settles, success or failure.
  • Show results with something else. useFormStatus reports progress, not outcome. For a message or error use useActionState; for instant feedback use useOptimistic.
  • Several forms: each component reads its own nearest parent form, so one SubmitButton can be reused in every form.
  • Accessibility: a pending submit button should still read sensibly to screen readers. Keep the visible text and consider aria-busy on the form.