How to Use useFormStatus in Next.js for Form Submission Status

In Next.js, useFormStatus is a hook that lets you track the submission state of a form inside a server action or client component. You use it by calling const { pending } = useFormStatus() inside your form component to know if the form is currently submitting, enabling you to show loading indicators or disable inputs.

Syntax

The useFormStatus hook returns an object with a pending boolean property. This indicates if the form submission is in progress.

Use it inside a React component that contains a form using Next.js server actions.

Example parts:

• const { pending }: Destructures the pending state.
• useFormStatus(): Hook to get form submission status.

javascript

const { pending } = useFormStatus();

Example

This example shows a simple form with a submit button. When the form is submitting, the button text changes to "Submitting..." and the button is disabled to prevent multiple submissions.

javascript

import { useFormStatus } from 'next/navigation';

export default function ContactForm() {
  const { pending } = useFormStatus();

  async function handleSubmit(data) {
    'use server';
    // Simulate async action
    await new Promise((resolve) => setTimeout(resolve, 2000));
    // Normally handle form data here
  }

  return (
    <form action={handleSubmit}>
      <input name="email" type="email" required placeholder="Your email" />
      <button type="submit" disabled={pending} aria-busy={pending}>
        {pending ? 'Submitting...' : 'Submit'}
      </button>
    </form>
  );
}

Output

<form> with an email input and a submit button that shows "Submitting..." and disables while submitting</form>

Common Pitfalls

• Using useFormStatus outside a form with a server action will not work because it depends on the form submission context.
• Not disabling the submit button during pending state can cause multiple submissions.
• Forgetting to mark the server action with 'use server' can cause errors.

javascript

/* Wrong: useFormStatus outside form or without server action */
const { pending } = useFormStatus(); // No form context, pending will always be false

/* Right: useFormStatus inside form with server action */
export default function Form() {
  const { pending } = useFormStatus();
  async function action(data) {
    'use server';
    // handle data
  }
  return <form action={action}><button disabled={pending}>Submit</button></form>;
}

Quick Reference

Feature	Description
useFormStatus()	Hook to get form submission status
pending	Boolean indicating if form is submitting
Disable inputs	Use pending to disable buttons or inputs during submit
Server action	Form must use a server action marked with 'use server'
Accessibility	Use aria-busy={pending} to inform screen readers

Key Takeaways

useFormStatus tracks if a Next.js form is currently submitting.

Destructure { pending } from useFormStatus to get submission state.

Disable submit buttons during pending to prevent duplicate submits.

useFormStatus only works inside forms using server actions.

Add aria-busy attribute for better accessibility during submission.