useFormStatus

Canary

The useFormStatus Hook is currently only available in React’s canary and experimental channels. Learn more about React’s release channels here.

useFormStatus is a Hook that gives you status information of the last form submission.

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

Reference
- useFormStatus()
Usage
- Display a pending state during form submission
- Read the form data being submitted
Troubleshooting
- status.pending is never true

Reference

`useFormStatus()`

The useFormStatus Hook provides status information of the last form submission.

import action from './actions';

function Button() {
  const status = useFormStatus();
  return <button disabled={status.pending}>Submit</button>
}

export default App() {
  return (
    <form action={action}>
      <Button />
    </form>
  );
}

To get status information, the Button component must be rendered within a <form>. The Hook returns information like the pending property which tells you if the form is actively submitting.

In the above example, Button uses this information to disable <button> presses while the form is submitting.

See more examples below.

Parameters

useFormStatus does not take any parameters.

Returns

A status object with the following properties:

pending: A boolean. If true, this means the parent <form> is pending submission. Otherwise, false.
data: An object implementing the FormData interface that contains the data the parent <form> is submitting. null if there is no active submission or no parent <form>.
method: A string value of either 'get' or 'post'. This represents whether the parent <form> is submitting with either GET or POST HTTP method. By default, a <form> will use GET method and can be specified by the method property.

action: A reference to the function passed to the action prop on the parent <form> which is called during submission. If action is unset on <form> or there is no parent <form>, the property is null.

Caveats

The useFormStatus Hook must be called from a component that is rendered inside a <form>.
useFormStatus will only return status information for a parent <form>. It will not return status information for any <form> rendered in that same component or children components.

Usage

Display a pending state during form submission

To display a pending state while a form is submitting, you can call the useFormStatus Hook in a component rendered in a <form> and read the pending property returned.

Here, we use the pending property to indicate the form is submitting.

Fork

import { useFormStatus } from "react-dom";
import { submitForm } from "./actions.js";

function Button() {
  const { pending } = useFormStatus();
  return (
    <button type="submit" disabled={pending}>
      {pending ? "Submitting..." : "Submit"}
    </button>
  );
}

function Form({ action }) {
  return (
    <form action={action}>
      <Button />
    </form>
  );
}

export default function App() {
  return <Form action={submitForm} />;
}

Pitfall

`useFormStatus` will not return status information for a `<form>` rendered in the same component.

The useFormStatus Hook only returns status information for a parent <form> and not for any <form> rendered in the same component calling the Hook, or child components.

function Form() {
  // 🚩 `pending` will never be true
  // useFormStatus does not track the form rendered in this component
  const { pending } = useFormStatus() 
  return <form action={submit}></form>
}

Instead call useFormStatus from inside a component that is located inside <form>.

function Button() {
    // ✅ `pending` will be derived from the 
    // form that wraps the Button component
    const { pending } = useFormStatus() 
    return <button disabled={pending}>...</button>
}

function Form() {
  // This is the <form> `useFormStatus` tracks
  return (
    <form action={submit}>
      <Button />
    </form>
  );
}

Read the form data being submitted

You can use the data property of the status information returned from useFormStatus to display what data is being submitted by the user.

Here, we have a form where users can request a username. We can use useFormStatus to display a temporary status message confirming what username they have requested.

Fork

import {useState, useMemo, useRef} from 'react';
import {useFormStatus} from 'react-dom';

export default function UsernameForm() {
  const {pending, data} = useFormStatus();

  const [showSubmitted, setShowSubmitted] = useState(false);
  const submittedUsername = useRef(null);
  const timeoutId = useRef(null);

  useMemo(() => {
    if (pending) {
      submittedUsername.current = data?.get('username');
      if (timeoutId.current != null) {
        clearTimeout(timeoutId.current);
      }

      timeoutId.current = setTimeout(() => {
        timeoutId.current = null;
        setShowSubmitted(false);
      }, 2000);
      setShowSubmitted(true);
    }
  }, [pending, data]);

  return (
    <>
      <label>Request a Username: </label><br />
      <input type="text" name="username" />
      <button type="submit" disabled={pending}>
        {pending ? 'Submitting...' : 'Submit'}
      </button>
      {showSubmitted ? (
        <p>Submitted request for username: {submittedUsername.current}</p>
      ) : null}
    </>
  );
}

Troubleshooting

`status.pending` is never `true`

useFormStatus will only return status information for a parent <form>.

If the component that calls useFormStatus is not nested in a <form>, the returned status object will always return false for the pending property.

useFormStatus will not track the status of a <form> rendered in the same component. See Pitfall for more details.

PreviousHooks NextComponents

useFormStatusThis feature is available in the latest Canary