React 19+ · Hook

useActionState

useActionState updates component state from a form action's result. It returns the latest state, a form-compatible action, and a pending flag.

Since: React 19

How it works

Call this Hook at component level with an action and initial serializable state. React passes the previous state into the action, then returns the action's latest result, a form-compatible wrapped action, and a pending flag.

Syntax

const [state, formAction, isPending] = useActionState(fn, initialState, permalink?);

Parameters

Name	Type	Description
`fn`	`function`	Function called when the form is submitted or a button is pressed. It receives previous form state first, then the normal form-action arguments.
`initialState`	`any serializable value`	Initial state value. It may be any serializable value and is used before the action runs.
`permalink`	`string`	Optional permalink used with progressive enhancement for forms that may submit before hydration.

Returns

An array: [state, formAction, isPending]. state is the current or latest action result; formAction is the wrapped action for a form or button; isPending indicates whether a Transition is pending.

Key points

Use it when a form submission should update component state from the action's returned result.
The action receives its previous state first, followed by the arguments normally supplied to a form action.
The state represents the most recent completed action result.
Use the returned action as a form action or as a button's formAction.
The returned action is not limited to declarative form submission; it can also be invoked within a transition.
Use isPending to disable controls or show progress while the action is pending.

Common mistakes

It is a Hook, so call it at the top level of a component or custom Hook—not inside loops or conditions.
The initialState value only seeds the first render; later state comes from the action's returned value.
Use an initial state that can be serialized, especially when integrating with server-rendered or server-function workflows.

Example: Form action with validation and pending UI

import { useActionState } from 'react';

async function saveName(previousState: {error: string | null}, formData: FormData) {
  const name = String(formData.get('name') ?? '').trim();
  if (!name) return {error: 'Enter a name'};
  await new Promise((resolve) => setTimeout(resolve, 300));
  return {error: null};
}

export default function NameForm() {
  const [state, formAction, isPending] = useActionState(saveName, {error: null});
  return (
    <form action={formAction}>
      <input name="name" disabled={isPending} />
      <button disabled={isPending}>{isPending ? 'Saving…' : 'Save'}</button>
      {state.error && <p role="alert">{state.error}</p>}
    </form>
  );
}

The action receives the previous state and submitted FormData, while the hook exposes the latest result and pending status for the form UI.

When to use it

Form result handling

Show validation errors or a success message returned by a submitted form action.

Pending-state feedback

Disable inputs and display progress while an asynchronous action is running.

Server-backed forms

Use a server function while preserving progressive enhancement and the latest response.

Manual action invocation

Invoke an action within a transition when a form element is not the direct caller.

useOptimistic
startTransition
useFormStatus
Server Functions

Source: useActionState – React. Checked 2026-10-15.