useFormState (now useActionState): State for Actions

Why it exists

Before React Actions, managing form submission state—loading, errors, success—required combining useState, useEffect, and manual logic to connect the UI to an async request. useActionState provides a dedicated, built-in pattern for this common use case, simplifying state management for operations that have a pending and final state, especially with Server Components.

The mental model

Think of useActionState as a specialized useReducer for async actions. You define how state should change in response to an action's outcome. The hook automatically gives you a loading status (isPending) while the action runs, then provides the action's result to your reducer function to compute the next state. It packages the entire async state lifecycle into one hook.

How it works

You call useActionState at the top level of your component with a reducer function and an initial state. It returns an array with three values: the current state, a dispatchAction function, and the isPending boolean. You pass dispatchAction to your form's action prop or a button's formAction. When the action is triggered, React sets isPending to true. When your async function (like a Server Action) completes, React sets isPending to false and feeds the return value into your reducer to calculate the new state.

When to use it

Its primary use case is handling UI state for form submissions. It's perfect for showing loading spinners on buttons, displaying validation errors returned from a Server Action, or showing a success message after a mutation. It integrates seamlessly with the action prop on <form> elements and is often used alongside useOptimistic for more responsive UIs.

When not to use it

Avoid this hook for general component state that isn't directly tied to the result of an async action. For simple, local, synchronous state, useState is simpler and more direct. For complex synchronous state transitions involving multiple sub-actions, useReducer is the more general tool. useActionState is specifically for state that is a result of an action.

One canonical example

Consider a username change form. The initial state might be { message: null }. The user submits a new username. This calls dispatchAction, which triggers a Server Action. isPending becomes true, and you disable the form. The server action checks if the username is available. If not, it returns { message: "Username taken" }. This result is passed to your reducer, which updates the state. Your component re-renders, displaying "Username taken" next to the input.