useFormState

const [state, formAction] = useFormState(action, initalState);

• Reference
  • useFormState()
• Usage
  • Using information returned by a form action
• Troubleshooting
  • My action can no longer read the submitted form data

Reference

useFormState()

In the context of React Server Components, an action is a function that may be executed when a form is submitted. You can execute actions on the server or on the client.

Call useFormState at the top level of your component to see the return value of an action after submitting a form. You pass useFormState an existing action as well as an initial state, and it returns a new action that you use when submitting your form, along with the latest form state.

function AddToCart({itemID}) {
  const [message, formAction] = useFormState(addToCartAction, null);
  return (
    <form action={formAction}>
      <input type="hidden" name="itemID" value={itemID} />
      <button type="submit" label="Add to cart" />
      <p>
        {message}
      </p>
    </form>
  )
}

The form state is the value returned by the action when the form was last submitted. If the form has not yet been submitted, it is the initial state that you pass.

If used with a server action, useFormState allows the server’s response from submitting the form to be shown even before hydration has completed.

See more examples below.

Parameters

• action: The action to be performed when the form is submitted. When the action is called, it will receive the previous state of the form (initially the initialState that you pass, subsequently its previous return value) as its initial argument, followed by the arguments that an action normally receives.
• initialState: The value you want the state to be initially. It can be any serializable value. This argument is ignored after the form is first submitted.

Returns

useFormState returns an array with exactly two values:

1. The current state. During the first render, it will match the initialState you have passed. After the form is submitted, it will match the value returned by the action.
2. A new action that you can pass as the action prop to your form component.

Caveats

• When used with a framework that supports React Server Components, useFormState lets you make forms interactive before JavaScript has executed on the client. When used without Server Components, there is no advantage to using it over component local state.
• The action passed to useFormState receives an extra argument, the previous or initial state state, as its first argument. This makes its signature different than if it were used directly without useFormState.

Usage

Using information returned by a form action

Call useFormState at the top level of your component to access the return value of an action from the last time a form was submitted.

import { useFormState } from 'react-dom';
import { action } from './actions.js';

function MyComponent() {
  const [state, formAction] = useFormState(action, null);
  // ...
  return (
    <form action={formAction}>
      {/* ... */}
    </form>
  );
}

useFormState returns an array with exactly two items:

1. The current state of the form, which is initially set to the initial state you provided, and after the form is submitted is set to the return value of the action you provided.
2. A new action that you pass to <form> as its action prop.

When the form is submitted, the action that you provided will be called. Its return value will become the new current state of the form.

The action that you provide will also receive a new first argument, namely the current state of the form. The first time the form is submitted, this will be the initial state you provided, while with subsequent submissions, it will be the return value from the last time the action was called. The rest of the arguments are the same as if useFormState had not been used

function action(currentState, formData) {
  // ...
  return 'next state';
}

Troubleshooting

My action can no longer read the submitted form data

When you wrap an action with useFormState, it gets an extra argument as its first argument. The submitted form data is therefore its second argument instead of its first as it would usually be. The new first argument that gets added is the current state of the form.

function action(currentState, formData) {
  // ...
}