React Hooks

useFormStatus Hook

🪝 Introduction to useFormStatus

The useFormStatus Hook is a React Hook that provides information about the current submission status of the nearest parent form. It is primarily used with forms that use React Actions, allowing components inside the form to react to submission progress without manually managing loading state.

Important

useFormStatus is designed for components rendered inside a form. It is commonly used to disable submit buttons, display loading indicators, and improve the user experience during form submission.

🎯 Why Use useFormStatus?

When a form is submitted, users should receive immediate feedback that their request is being processed. Instead of creating separate loading state variables, useFormStatus automatically exposes the current submission status of the nearest parent form.

Display form submission progress.
Disable submit buttons while a form is submitting.
Prevent duplicate submissions.
Create cleaner form components with less boilerplate.

⚙️ Syntax

Basic Syntax

const {
  pending,
  data,
  method,
  action
} = useFormStatus();

Property	Description
pending	Indicates whether the parent form is currently submitting.
data	The submitted FormData while the submission is in progress.
method	The HTTP method used for the form submission.
action	The action currently handling the form submission.

🔄 How useFormStatus Works

User Submits the Form

React Starts the Form Action

pending Becomes true

Child Components Read Form Status

Action Completes

pending Returns to false

💻 Example 1: Disabling the Submit Button

Basic useFormStatus Example

import { useFormStatus } from "react-dom";

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

  return (
    <button disabled={pending}>
      {pending ? "Submitting..." : "Submit"}
    </button>
  );
}

The button automatically becomes disabled while the parent form is submitting, preventing duplicate form submissions.

💻 Example 2: Using the Submit Button Inside a Form

Complete Form Example

import { useFormStatus } from "react-dom";

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

  return (
    <button disabled={pending}>
      {pending ? "Saving..." : "Save"}
    </button>
  );
}

export default function ContactForm() {
  async function submit(formData) {
    "use server";

    console.log(formData.get("name"));
  }

  return (
    <form action={submit}>
      <input
        name="name"
        placeholder="Your name"
      />

      <SubmitButton />
    </form>
  );
}

The SubmitButton automatically tracks the status of the surrounding form without receiving any props.

📊 Manual Loading State vs useFormStatus

Manual State	useFormStatus
Requires useState for loading.	Loading state is provided automatically.
Manual updates before and after submission.	React manages the submission status.
More boilerplate code.	Cleaner and simpler implementation.
Easy to forget resetting loading state.	Status automatically reflects the form lifecycle.

📅 Form Submission Timeline

📝

The user fills out the form.

🚀

The user submits the form.

⏳

pending becomes true, allowing the UI to display loading feedback.

⚙️

The form action processes the submitted data.

✅

After completion, pending returns to false and the form becomes interactive again.

🎯 Common Use Cases

Buttons

Validation

Forms

Disable submit buttons while a form is processing.

Display loading indicators or progress messages during submission.

Prevent repeated submissions while server-side validation is running.

Build reusable form components that automatically react to submission status.

📊 useFormStatus vs useActionState

Feature	useFormStatus	useActionState
Purpose	Track the current form submission status.	Store and update state returned by an action.
Main Focus	Loading and submission progress.	Action results such as success or validation errors.
Returns	Status information about the form.	State, action function, and pending status.
Typical Usage	Submit buttons and loading indicators.	Managing form results and validation messages.

⚠️ Common Mistakes

Using useFormStatus outside a component rendered inside a form.
Expecting it to manage form data or validation results.
Creating manual loading state when pending already provides the necessary information.
Using it for forms that do not use React Actions.

Warning

useFormStatus reads the status of the nearest parent form. Components outside that form cannot access its submission status.

✅ Best Practices

Use useFormStatus inside reusable submit button components.
Disable form controls while pending is true.
Show clear loading feedback during submissions.
Combine useFormStatus with useActionState when you need both submission status and action results.
Keep status-related UI separate from business logic.

📚 Official Resource

Learn more about useFormStatus in the official React documentation at React useFormStatus Documentation.

Summary

The useFormStatus Hook provides an easy way to monitor the submission status of the nearest parent form. It is ideal for disabling buttons, displaying loading indicators, and preventing duplicate submissions without manually managing loading state. When combined with React Actions, it helps create clean, responsive, and user-friendly form experiences.