useFormStatus

Kind: Function

Source: src/jsx/dom/hooks/index.ts

Part of: Jsx

This hook returns the current form status

useFormStatus reads the status associated with the nearest parent form while a form action is running. Call it from a component rendered inside that form to update UI based on the current status.

Signature

ts
function useFormStatus(): FormStatus

Returns: FormStatus

Diagram

mermaid
graph LR
  Form[Form] --> Child[Child component]
  Child --> Hook[useFormStatus]
  Hook --> Status[Current form status]
  Status --> UI[Button and feedback UI]

Usage

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

function SubmitButton() {
  const { pending } = useFormStatus();

  return (
    <button type="submit" disabled={pending}>
      {pending ? "Saving…" : "Save changes"}
    </button>
  );
}

async function saveProfile(formData: FormData) {
  await fetch("/api/profile", {
    method: "POST",
    body: formData,
  });
}

export function ProfileForm() {
  return (
    <form action={saveProfile}>
      <label>
        Name
        <input name="name" required />
      </label>

      <SubmitButton />
    </form>
  );
}

AI Coding Instructions

• Call useFormStatus from a component nested inside the related <form>.
• Do not call the hook in the same component that renders the <form> when reading that form’s status.
• Use the returned status to disable submit controls while the form action is pending.
• Keep status-dependent UI near the form controls that it affects.