useActionState

const [state, dispatchAction, isPending] = useActionState(reducerAction, initialState, permalink?);

• Reference
  • useActionState(reducerAction, initialState, permalink?)
  • reducerAction function
• Usage
  • Adding state to an Action
  • Using multiple Action types
  • Using with useOptimistic
  • Using with Action props
  • Cancelling queued Actions
  • Using with <form> Action props
  • Handling errors
• Troubleshooting
  • My isPending flag is not updating
  • My Action cannot read form data
  • My actions are being skipped
  • My state doesn’t reset
  • I’m getting an error: “An async function with useActionState was called outside of a transition.”
  • I’m getting an error: “Cannot update action state while rendering”

Reference

useActionState(reducerAction, initialState, permalink?)

Call useActionState at the top level of your component to create state for the result of an Action.

import { useActionState } from 'react';

function reducerAction(previousState, actionPayload) {
  // ...
}

function MyCart({initialState}) {
  const [state, dispatchAction, isPending] = useActionState(reducerAction, initialState);
  // ...
}

See more examples below.

Parameters

• reducerAction: The function to be called when the Action is triggered. When called, it receives the previous state (initially the initialState you provided, then its previous return value) as its first argument, followed by the actionPayload passed to dispatchAction.
• initialState: The value you want the state to be initially. React ignores this argument after dispatchAction is invoked for the first time.
• optional permalink: A string containing the unique page URL that this form modifies.
  • For use on pages with React Server Components with progressive enhancement.
  • If reducerAction is a Server Function and the form is submitted before the JavaScript bundle loads, the browser will navigate to the specified permalink URL rather than the current page’s URL.

Returns

useActionState returns an array with exactly three values:

1. The current state. During the first render, it will match the initialState you passed. After dispatchAction is invoked, it will match the value returned by the reducerAction.
2. A dispatchAction function that you call inside Actions.
3. The isPending flag that tells you if any dispatched Actions for this Hook are pending.

Caveats

• useActionState is a Hook, so you can only call it at the top level of your component or your own Hooks. You can’t call it inside loops or conditions. If you need that, extract a new component and move the state into it.
• React queues and executes multiple calls to dispatchAction sequentially. Each call to reducerAction receives the result of the previous call.
• The dispatchAction function has a stable identity, so you will often see it omitted from Effect dependencies, but including it will not cause the Effect to fire. If the linter lets you omit a dependency without errors, it is safe to do. Learn more about removing Effect dependencies.
• When using the permalink option, ensure the same form component is rendered on the destination page (including the same reducerAction and permalink) so React knows how to pass the state through. Once the page becomes interactive, this parameter has no effect.
• When using Server Functions, initialState needs to be serializable (values like plain objects, arrays, strings, and numbers).
• If dispatchAction throws an error, React cancels all queued actions and shows the nearest Error Boundary.
• If there are multiple ongoing Actions, React batches them together. This is a limitation that may be removed in a future release.

reducerAction function

The reducerAction function passed to useActionState receives the previous state and returns a new state.

Unlike reducers in useReducer, the reducerAction can be async and perform side effects:

async function reducerAction(previousState, actionPayload) {
  const newState = await post(actionPayload);
  return newState;
}

Each time you call dispatchAction, React calls the reducerAction with the actionPayload. The reducer will perform side effects such as posting data, and return the new state. If dispatchAction is called multiple times, React queues and executes them in order so the result of the previous call is passed as previousState for the current call.

Parameters

• previousState: The last state. Initially this is equal to the initialState. After the first call to dispatchAction, it’s equal to the last state returned.

• optional actionPayload: The argument passed to dispatchAction. It can be a value of any type. Similar to useReducer conventions, it is usually an object with a type property identifying it and, optionally, other properties with additional information.

Returns

reducerAction returns the new state, and triggers a Transition to re-render with that state.

Caveats

• reducerAction can be sync or async. It can perform sync actions like showing a notification, or async actions like posting updates to a server.
• reducerAction is not invoked twice in <StrictMode> since reducerAction is designed to allow side effects.
• The return type of reducerAction must match the type of initialState. If TypeScript infers a mismatch, you may need to explicitly annotate your state type.
• If you set state after await in the reducerAction you currently need to wrap the state update in an additional startTransition. See the startTransition docs for more info.
• When using Server Functions, actionPayload needs to be serializable (values like plain objects, arrays, strings, and numbers).

Usage

Adding state to an Action

Call useActionState at the top level of your component to create state for the result of an Action.

import { useActionState } from 'react';

async function addToCartAction(prevCount) {
  // ...
}
function Counter() {
  const [count, dispatchAction, isPending] = useActionState(addToCartAction, 0);

  // ...
}

useActionState returns an array with exactly three items:

1. The current state, initially set to the initial state you provided.
2. The action dispatcher that lets you trigger reducerAction.
3. A pending state that tells you whether the Action is in progress.

To call addToCartAction, call the action dispatcher. React will queue calls to addToCartAction with the previous count.

Every time you click “Add Ticket,” React queues a call to addToCartAction. React shows the pending state until all the tickets are added, and then re-renders with the final state.

Using multiple Action types

To handle multiple types, you can pass an argument to dispatchAction.

By convention, it is common to write it as a switch statement. For each case in the switch, calculate and return some next state. The argument can have any shape, but it is common to pass objects with a type property identifying the action.

When you click to increase or decrease the quantity, an "ADD" or "REMOVE" is dispatched. In the reducerAction, different APIs are called to update the quantity.

In this example, we use the pending state of the Actions to replace both the quantity and the total. If you want to provide immediate feedback, such as immediately updating the quantity, you can use useOptimistic.

Using with useOptimistic

You can combine useActionState with useOptimistic to show immediate UI feedback:

setOptimisticCount immediately updates the quantity, and dispatchAction() queues the updateCartAction. A pending indicator appears on both the quantity and total to give the user feedback that their update is still being applied.

Using with Action props

When you pass the dispatchAction function to a component that exposes an Action prop, you don’t need to call startTransition or useOptimistic yourself.

This example shows using the increaseAction and decreaseAction props of a QuantityStepper component:

Since <QuantityStepper> has built-in support for transitions, pending state, and optimistically updating the count, you just need to tell the Action what to change, and how to change it is handled for you.

Cancelling queued Actions

You can use an AbortController to cancel pending Actions:

Try clicking increase or decrease multiple times, and notice that the total updates within 1 second no matter how many times you click. This works because it uses an AbortController to “complete” the previous Action so the next Action can proceed.

Using with <form> Action props

You can pass the dispatchAction function as the action prop to a <form>.

When used this way, React automatically wraps the submission in a Transition, so you don’t need to call startTransition yourself. The reducerAction receives the previous state and the submitted FormData:

In this example, when the user clicks the stepper arrows, the button submits the form and useActionState calls updateCartAction with the form data. The example uses useOptimistic to immediately show the new quantity while the server confirms the update.

See the <form> docs for more information on using Actions with forms.

Handling errors

There are two ways to handle errors with useActionState.

For known errors, such as “quantity not available” validation errors from your backend, you can return it as part of your reducerAction state and display it in the UI.

For unknown errors, such as undefined is not a function, you can throw an error. React will cancel all queued Actions and shows the nearest Error Boundary by rethrowing the error from the useActionState hook.

In this example, “Add 10” simulates an API that returns a validation error, which updateCartAction stores in state and displays inline. “Add NaN” results in an invalid count, so updateCartAction throws, which propagates through useActionState to the ErrorBoundary and shows a reset UI.

Troubleshooting

My isPending flag is not updating

If you’re calling dispatchAction manually (not through an Action prop), make sure you wrap the call in startTransition:

import { useActionState, startTransition } from 'react';

function MyComponent() {
  const [state, dispatchAction, isPending] = useActionState(myAction, null);

  function handleClick() {
    // ✅ Correct: wrap in startTransition
    startTransition(() => {
      dispatchAction();
    });
  }

  // ...
}

When dispatchAction is passed to an Action prop, React automatically wraps it in a Transition.

My Action cannot read form data

When you use useActionState, the reducerAction receives an extra argument as its first argument: the previous or initial state. The submitted form data is therefore its second argument instead of its first.

// Without useActionState
function action(formData) {
  const name = formData.get('name');
}

// With useActionState
function action(prevState, formData) {
  const name = formData.get('name');
}

My actions are being skipped

If you call dispatchAction multiple times and some of them don’t run, it may be because an earlier dispatchAction call threw an error.

When a reducerAction throws, React skips all subsequently queued dispatchAction calls.

To handle this, catch errors within your reducerAction and return an error state instead of throwing:

async function myReducerAction(prevState, data) {
  try {
    const result = await submitData(data);
    return { success: true, data: result };
  } catch (error) {
    // ✅ Return error state instead of throwing
    return { success: false, error: error.message };
  }
}

My state doesn’t reset

useActionState doesn’t provide a built-in reset function. To reset the state, you can design your reducerAction to handle a reset signal:

const initialState = { name: '', error: null };

async function formAction(prevState, payload) {
  // Handle reset
  if (payload === null) {
    return initialState;
  }
  // Normal action logic
  const result = await submitData(payload);
  return result;
}

function MyComponent() {
  const [state, dispatchAction, isPending] = useActionState(formAction, initialState);

  function handleReset() {
    startTransition(() => {
      dispatchAction(null); // Pass null to trigger reset
    });
  }

  // ...
}

Alternatively, you can add a key prop to the component using useActionState to force it to remount with fresh state, or a <form> action prop, which resets automatically after submission.

I’m getting an error: “An async function with useActionState was called outside of a transition.”

A common mistake is to forget to call dispatchAction from inside a Transition:

This error happens because dispatchAction must run inside a Transition:

function MyComponent() {
  const [state, dispatchAction, isPending] = useActionState(myAsyncAction, null);

  function handleClick() {
    // ❌ Wrong: calling dispatchAction outside a Transition
    dispatchAction();
  }

  // ...
}

To fix, either wrap the call in startTransition:

import { useActionState, startTransition } from 'react';

function MyComponent() {
  const [state, dispatchAction, isPending] = useActionState(myAsyncAction, null);

  function handleClick() {
    // ✅ Correct: wrap in startTransition
    startTransition(() => {
      dispatchAction();
    });
  }

  // ...
}

Or pass dispatchAction to an Action prop, is call in a Transition:

function MyComponent() {
  const [state, dispatchAction, isPending] = useActionState(myAsyncAction, null);

  // ✅ Correct: action prop wraps in a Transition for you
  return <Button action={dispatchAction}>...</Button>;
}

I’m getting an error: “Cannot update action state while rendering”

You cannot call dispatchAction during render:

This causes an infinite loop because calling dispatchAction schedules a state update, which triggers a re-render, which calls dispatchAction again.

function MyComponent() {
  const [state, dispatchAction, isPending] = useActionState(myAction, null);

  // ❌ Wrong: calling dispatchAction during render
  dispatchAction();

  // ...
}

To fix, only call dispatchAction in response to user events (like form submissions or button clicks).