diff --git a/src/content/reference/react/useActionState.md b/src/content/reference/react/useActionState.md
index f83f6bdc710..3c961c9d23e 100644
--- a/src/content/reference/react/useActionState.md
+++ b/src/content/reference/react/useActionState.md
@@ -4,269 +4,1320 @@ title: useActionState
-`useActionState` is a Hook that allows you to update state based on the result of a form action.
+`useActionState` is a React Hook that lets you track the state of an [Action](/reference/react/useTransition#functions-called-in-starttransition-are-called-actions).
```js
-const [state, formAction, isPending] = useActionState(fn, initialState, permalink?);
+const [state, action, isPending] = useActionState(reducerAction, initialState, permalink?);
```
-
-
-In earlier React Canary versions, this API was part of React DOM and called `useFormState`.
-
-
-
-
---
## Reference {/*reference*/}
-### `useActionState(action, initialState, permalink?)` {/*useactionstate*/}
+### `useActionState(reducerAction, initialState, permalink?)` {/*useactionstate*/}
-{/* TODO T164397693: link to actions documentation once it exists */}
-
-Call `useActionState` at the top level of your component to create component state that is updated [when a form action is invoked](/reference/react-dom/components/form). You pass `useActionState` an existing form action function as well as an initial state, and it returns a new action that you use in your form, along with the latest form state and whether the Action is still pending. The latest form state is also passed to the function that you provided.
+Call `useActionState` at the top level of your component to create state for the result of an Action.
```js
-import { useActionState } from "react";
+import { useActionState } from 'react';
-async function increment(previousState, formData) {
- return previousState + 1;
+function reducerAction(state, action) {
+ // ...
}
-function StatefulForm({}) {
- const [state, formAction] = useActionState(increment, 0);
- return (
-
- )
+function MyComponent() {
+ const [state, action, isPending] = useActionState(reducerAction, {quantity: 1});
+ // ...
}
```
-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 Function, `useActionState` allows the server's response from submitting the form to be shown even before hydration has completed.
-
[See more examples below.](#usage)
#### Parameters {/*parameters*/}
-* `fn`: The function to be called when the form is submitted or button pressed. When the function 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 a form 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 action is first invoked.
-* **optional** `permalink`: A string containing the unique page URL that this form modifies. For use on pages with dynamic content (eg: feeds) in conjunction with progressive enhancement: if `fn` is a [server function](/reference/rsc/server-functions) 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. Ensure that the same form component is rendered on the destination page (including the same action `fn` and `permalink`) so that React knows how to pass the state through. Once the form has been hydrated, this parameter has no effect.
-
-{/* TODO T164397693: link to serializable values docs once it exists */}
+* `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 arguments passed to the `action`.
+* `initialState`: The value you want the state to be initially. React ignores this argument after invoking the action 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](/reference/rsc/server-components) with progressive enhancement.
+ * If `reducerAction` is a [Server Function](/reference/rsc/server-functions) 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 {/*returns*/}
-`useActionState` returns an array with the following values:
+`useActionState` returns an array with exactly three values:
-1. The current state. During the first render, it will match the `initialState` you have passed. After the action is invoked, 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 or `formAction` prop to any `button` component within the form. The action can also be called manually within [`startTransition`](/reference/react/startTransition).
-3. The `isPending` flag that tells you whether there is a pending Transition.
+1. The current state. During the first render, it will match the `initialState` you passed. After the action is invoked, it will match the value returned by the `reducerAction`.
+2. An `action` function that you call inside [Actions](/reference/react/useTransition#functions-called-in-starttransition-are-called-actions).
+3. The `isPending` flag that tells you whether there is a pending Action.
#### Caveats {/*caveats*/}
-* When used with a framework that supports React Server Components, `useActionState` lets you make forms interactive before JavaScript has executed on the client. When used without Server Components, it is equivalent to component local state.
-* The function passed to `useActionState` receives an extra argument, the previous or initial state, as its first argument. This makes its signature different than if it were used directly as a form action without using `useActionState`.
+* `useActionState` is a Hook, so it must be called **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 `action` sequentially, allowing each `reducerAction` to use the result of the previous Action.
+* The `action` 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.](/learn/removing-effect-dependencies#move-dynamic-objects-and-functions-inside-your-effect)
+* 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 `action` throws an error, React cancels all queued actions and shows the nearest [Error Boundary](/reference/react/Component#catching-rendering-errors-with-an-error-boundary).
+
+
+
+When calling the `action` function, you must wrap the call in [`startTransition`](/reference/react/startTransition). If you call `action` without `startTransition`, the `isPending` flag will not update correctly, and React will show a warning in development.
+
+
+
+---
+
+### `reducerAction` function {/*reduceraction*/}
+
+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:
+
+```js
+async function reducerAction(previousState, update) {
+ const newState = await post(update);
+ return newState;
+}
+
+function MyCart({initialCart}) {
+ const [state, action, isPending] = useActionState(reducerAction, initialCart);
+ // ...
+}
+```
+
+Each time you call `action`, React calls the `reducerAction` to perform side effects and compute the result of that Action. If the `action` is called multiple times, React queues and executes them in order so the result of the previous call is available for current call.
+
+#### Parameters {/*reduceraction-parameters*/}
+
+* `previousState`: The current state of the Action. Initially this is equal to the `initialState`. After the first call to `action`, it's equal to the last state returned.
+
+* `update`: The argument passed to `action`. 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*/}
+
+`reducerAction` returns the new state, and triggers a re-render with that state.
+
+#### Caveats {/*reduceraction-caveats*/}
+
+* `reducerAction` is not invoked twice in StrictMode since `reducerAction` is designed to allow side effects.
+
+
+
+#### Why is it called `reducerAction`? {/*why-is-it-called-reduceraction*/}
+
+The function passed to `useActionState` is called a *reducer action* because:
+
+- It *reduces* the previous state into a new state, like `useReducer`.
+- It's called inside a Transition and can perform side effects, like an Action.
+
+Conceptually, `useActionState` is like `useReducer`, but you can do side effects in the reducer.
+
+
---
## Usage {/*usage*/}
-### Using information returned by a form action {/*using-information-returned-by-a-form-action*/}
+### Adding state to an Action {/*adding-state-to-an-action*/}
-Call `useActionState` at the top level of your component to access the return value of an action from the last time a form was submitted.
+Call `useActionState` at the top level of your component to create state for the result of an Action.
-```js [[1, 5, "state"], [2, 5, "formAction"], [3, 5, "action"], [4, 5, "null"], [2, 8, "formAction"]]
+```js [[1, 7, "count"], [2, 7, "action"], [3, 7, "isPending"]]
import { useActionState } from 'react';
-import { action } from './actions.js';
-function MyComponent() {
- const [state, formAction] = useActionState(action, null);
+async function increment(prevCount) {
+ // ...
+}
+function Counter() {
+ const [count, action, isPending] = useActionState(increment, 0);
+
// ...
+}
+```
+
+`useActionState` returns an array with exactly three items:
+
+1. The current state, initially set to the initial state you provided.
+2. The `action` function that lets you trigger the `reducerAction`.
+3. The pending state that tells you whether `action` is in progress.
+
+To trigger the Action, call the `action` function inside an [Action](/reference/react/useTransition#functions-called-in-starttransition-are-called-actions). React will call your `reducerAction` with the previous state and argument passed to `action`, and return the new state.
+
+
+
+```js src/App.js
+import { useActionState, startTransition } from 'react';
+import { addToCart } from './api';
+import Total from './Total';
+
+async function addTicket(prevCount) {
+ return await addToCart(prevCount);
+}
+
+export default function Checkout() {
+ const [count, action, isPending] = useActionState(addTicket, 0);
+
+ function handleClick() {
+ startTransition(() => {
+ action();
+ });
+ }
+
return (
-
+
+ );
+}
+```
+
+```js src/api.js hidden
+export async function addToCart(count) {
+ await new Promise(resolve => setTimeout(resolve, 1000));
+ return count + 1;
+}
+
+export async function removeFromCart(count) {
+ await new Promise(resolve => setTimeout(resolve, 1000));
+ return Math.max(0, count - 1);
+}
+```
+
+```css
+.checkout {
+ display: flex;
+ flex-direction: column;
+ gap: 12px;
+ padding: 16px;
+ border: 1px solid #ccc;
+ border-radius: 8px;
+ font-family: system-ui;
+}
+
+.checkout h2 {
+ margin: 0 0 8px 0;
+}
-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 `
+
+Every time you click "Add Ticket," React queues a call to `addTicket`. React shows the pending state until all of the tickets are added, and then re-renders with the final state.
+
+
-#### Display form errors {/*display-form-errors*/}
+#### How `useActionState` queuing works {/*how-useactionstate-queuing-works*/}
-To display messages such as an error message or toast that's returned by a Server Function, wrap the action in a call to `useActionState`.
+Try clicking "Add Ticket" multiple times. Every time you click, a new `addTicket` is queued. Since there's an artificial 1 second delay, that means 4 clicks will take ~4 seconds to complete.
+
+**This is intentional in the design of `useActionState`.**
+
+We have to wait for the previous result of `addTicket` in order to pass the `prevCount` to the next call to `addTicket`. That means React has to wait for the previous Action to finish before calling the next Action.
+
+You can typically solve this by [using with useOptimistic](/reference/react/useActionState#using-with-useoptimistic) but for more complex cases you may want to consider [cancelling queued actions](#cancelling-queued-actions) or not using `useActionState`.
+
+
+
+### Using multiple Action types {/*using-multiple-action-types*/}
+
+To handle multiple types, you can pass an argument to `action`.
+
+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.
```js src/App.js
-import { useActionState, useState } from "react";
-import { addToCart } from "./actions.js";
+import { useActionState, startTransition } from 'react';
+import { addToCart, removeFromCart } from './api';
+import Total from './Total';
+
+export default function Checkout() {
+ const [count, action, isPending] = useActionState(updateCart, 0);
+
+ function handleAdd() {
+ startTransition(() => {
+ action({type: 'ADD'});
+ });
+ }
+
+ function handleRemove() {
+ startTransition(() => {
+ action({type: 'REMOVE'});
+ });
+ }
-function AddToCartForm({itemID, itemTitle}) {
- const [message, formAction, isPending] = useActionState(addToCart, null);
return (
-
+
+ );
+}
+```
+
+```js src/api.js hidden
+class AbortError extends Error {
+ name = "AbortError";
+ constructor(message = "The operation was aborted") {
+ super(message);
}
}
+
+function sleep(ms, signal){
+ if (!signal) return new Promise((resolve) => setTimeout(resolve, ms));
+ if (signal.aborted) return Promise.reject(new AbortError());
+
+ return new Promise((resolve, reject) => {
+ const id = setTimeout(() => {
+ signal.removeEventListener("abort", onAbort);
+ resolve();
+ }, ms);
+
+ const onAbort = () => {
+ clearTimeout(id);
+ reject(new AbortError());
+ };
+
+ signal.addEventListener("abort", onAbort, { once: true });
+ });
+}
+export async function addToCart(count, opts) {
+ await sleep(1000, opts?.signal);
+ return count + 1;
+}
+
+export async function removeFromCart(count, opts) {
+ await sleep(1000, opts?.signal);
+ return Math.max(0, count - 1);
+}
```
-```css src/styles.css hidden
-form {
- border: solid 1px black;
- margin-bottom: 24px;
- padding: 12px
+```css
+.checkout {
+ display: flex;
+ flex-direction: column;
+ gap: 12px;
+ padding: 16px;
+ border: 1px solid #ccc;
+ border-radius: 8px;
+ font-family: system-ui;
+}
+
+.checkout h2 {
+ margin: 0 0 8px 0;
+}
+
+.row {
+ display: flex;
+ justify-content: space-between;
+ align-items: center;
+}
+
+.stepper {
+ display: flex;
+ align-items: center;
+ gap: 8px;
+}
+
+.qty {
+ min-width: 20px;
+ text-align: center;
+}
+
+.buttons {
+ display: flex;
+ flex-direction: column;
+ gap: 2px;
+}
+
+.buttons button {
+ padding: 0 8px;
+ font-size: 10px;
+ line-height: 1.2;
+ cursor: pointer;
}
-form button {
- margin-right: 12px;
+.pending {
+ width: 20px;
+ text-align: center;
+}
+
+.total {
+ font-weight: bold;
+}
+
+hr {
+ width: 100%;
+ border: none;
+ border-top: 1px solid #ccc;
+ margin: 4px 0;
}
```
+
-
+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 we're using an AbortController to "complete" the previous Action so the next Action can proceed.
+
+
+
+Aborting an Action isn't always safe, which is why `useActionState` doesn't do it by default.
-
+
+
+---
## Troubleshooting {/*troubleshooting*/}
-### My action can no longer read the submitted form data {/*my-action-can-no-longer-read-the-submitted-form-data*/}
+### My action can no longer read the submitted form data {/*action-cant-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.
+
+```js
+// Without useActionState
+function action(formData) {
+ const name = formData.get('name');
+}
+
+// With useActionState
+function action(prevState, formData) {
+ const name = formData.get('name');
+}
+```
+
+---
+
+### My `isPending` flag is not updating {/*ispending-not-updating*/}
+
+If you're calling the action manually (not through a form's `action` prop), make sure you wrap the call in [`startTransition`](/reference/react/startTransition):
+
+```js
+import { useActionState, startTransition } from 'react';
+
+function MyComponent() {
+ const [state, action, isPending] = useActionState(myAction, null);
+
+ function handleClick() {
+ // ✅ Correct: wrap in startTransition
+ startTransition(() => {
+ action();
+ });
+ }
+
+ // ...
+}
+```
+
+When the action is passed to a form's `action` prop or a button's `formAction` prop, React automatically wraps it in a transition.
+
+---
+
+### I'm getting an error: "Cannot update form state while rendering" {/*cannot-update-during-render*/}
-When you wrap an action with `useActionState`, 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.
+You cannot call `action` during render. This causes an infinite loop because calling `action` schedules a state update, which triggers a re-render, which calls `action` again.
```js
-function action(currentState, formData) {
+function MyComponent() {
+ const [state, action, isPending] = useActionState(myAction, null);
+
+ // ❌ Wrong: calling action during render
+ action();
+
// ...
}
```
+
+Only call `action` in response to user events (like form submissions or button clicks) or in Effects.
+
+---
+
+### My actions are being skipped {/*actions-skipped*/}
+
+If you call `action` multiple times and some of them don't run, it may be because an earlier `action` call threw an error. When a `reducerAction` throws, React skips all subsequently queued `action` calls.
+
+To handle this, catch errors within your `reducerAction` and return an error state instead of throwing:
+
+```js
+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 };
+ }
+}
+```
+
+---
+
+### I want to reset the state {/*reset-state*/}
+
+`useActionState` doesn't provide a built-in reset function. To reset the state, you can design your `reducerAction` to handle a reset signal:
+
+```js
+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, action, isPending] = useActionState(formAction, initialState);
+
+ function handleReset() {
+ startTransition(() => {
+ action(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.