diff --git a/src/content/reference/react/useActionState.md b/src/content/reference/react/useActionState.md
index f83f6bdc710..ed17c24f0e3 100644
--- a/src/content/reference/react/useActionState.md
+++ b/src/content/reference/react/useActionState.md
@@ -4,269 +4,1562 @@ 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 update state with side effects using [Actions](/reference/react/useTransition#functions-called-in-starttransition-are-called-actions).
```js
-const [state, formAction, isPending] = useActionState(fn, initialState, permalink?);
+const [state, dispatchAction, 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(previousState, actionPayload) {
+ // ...
}
-function StatefulForm({}) {
- const [state, formAction] = useActionState(increment, 0);
- return (
-
- )
+function MyCart({initialState}) {
+ const [state, dispatchAction, isPending] = useActionState(reducerAction, initialState);
+ // ...
}
```
-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 `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](/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 `dispatchAction` is invoked, it will match the value returned by the `reducerAction`.
+2. A `dispatchAction` function that you call inside [Actions](/reference/react/useTransition#functions-called-in-starttransition-are-called-actions).
+3. The `isPending` flag that tells you if any dispatched Actions for this Hook are pending.
#### 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 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.](/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](/reference/rsc/use-server#serializable-parameters-and-return-values) (values like plain objects, arrays, strings, and numbers).
+* If `dispatchAction` throws an error, React cancels all queued actions and shows the nearest [Error Boundary](/reference/react/Component#catching-rendering-errors-with-an-error-boundary).
+* If there are multiple ongoing Actions, React batches them together. This is a limitation that may be removed in a future release.
+
+
+
+`dispatchAction` must be called from an Action.
+
+You can wrap it in [`startTransition`](/reference/react/startTransition), or pass it to an [Action prop](/reference/react/useTransition#exposing-action-props-from-components). Calls outside that scope wonβt be treated as part of the Transition and [log an error](#async-function-outside-transition) on development mode.
+
+
+
+---
+
+### `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, 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 {/*reduceraction-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*/}
+
+`reducerAction` returns the new state, and triggers a Transition to re-render with that state.
+
+#### Caveats {/*reduceraction-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 `` 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](/reference/react/useTransition#react-doesnt-treat-my-state-update-after-await-as-a-transition) docs for more info.
+* When using Server Functions, `actionPayload` needs to be [serializable](/reference/rsc/use-server#serializable-parameters-and-return-values) (values like plain objects, arrays, strings, and numbers).
+
+
+
+#### 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 an *Action* because it's called inside a Transition and can perform side effects.
+
+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, "dispatchAction"], [3, 7, "isPending"]]
import { useActionState } from 'react';
-import { action } from './actions.js';
-function MyComponent() {
- const [state, formAction] = useActionState(action, null);
+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.
+
+
+
+```js src/App.js
+import { useActionState, startTransition } from 'react';
+import { addToCart } from './api';
+import Total from './Total';
+
+export default function Checkout() {
+ const [count, dispatchAction, isPending] = useActionState(async (prevCount) => {
+ return await addToCart(prevCount)
+ }, 0);
+
+ function handleClick() {
+ startTransition(() => {
+ dispatchAction();
+ });
+ }
+
return (
-
+
);
}
```
-`useActionState` returns an array with the following items:
+```js src/api.js
+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 `addToCartAction`. React shows the pending state until all the tickets are added, and then re-renders with the final state.
+
+
+
+#### How `useActionState` queuing works {/*how-useactionstate-queuing-works*/}
+
+Try clicking "Add Ticket" multiple times. Every time you click, a new `addToCartAction` 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 `addToCartAction` in order to pass the `prevCount` to the next call to `addToCartAction`. That means React has to wait for the previous Action to finish before calling the next Action.
-#### Display form errors {/*display-form-errors*/}
+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`.
-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`.
+
+
+---
+
+### Using multiple Action types {/*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.
```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, dispatchAction, isPending] = useActionState(updateCartAction, 0);
+
+ function handleAdd() {
+ startTransition(() => {
+ dispatchAction({ type: 'ADD' });
+ });
+ }
+
+ function handleRemove() {
+ startTransition(() => {
+ dispatchAction({ type: 'REMOVE' });
+ });
+ }
-function AddToCartForm({itemID, itemTitle}) {
- const [message, formAction, isPending] = useActionState(addToCart, null);
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;
+}
+
+.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;
+}
+
+.pending {
+ width: 20px;
+ text-align: center;
+}
+
+.total {
+ font-weight: bold;
+}
+
+hr {
+ width: 100%;
+ border: none;
+ border-top: 1px solid #ccc;
+ margin: 4px 0;
}
```
-```js src/actions.js
-"use server";
+
+
+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`.
+
+
+
+#### How is `useActionState` different from `useReducer`? {/*useactionstate-vs-usereducer*/}
+
+You might notice this example looks a lot like `useReducer`, but they serve different purposes:
+
+- **Use `useReducer`** to manage state of your UI. The reducer must be pure.
+
+- **Use `useActionState`** to manage state of your Actions. The reducer can perform side effects.
+
+You can think of `useActionState` as `useReducer` for side effects from user Actions. Since it computes the next Action to take based on the previous Action, it has to [order the calls sequentially](/reference/react/useActionState#how-useactionstate-queuing-works). If you want to perform Actions in parallel, use `useState` and `useTransition` directly.
+
+
-export async function addToCart(prevState, queryData) {
- const itemID = queryData.get('itemID');
- if (itemID === "1") {
- return "Added to cart";
- } else {
- // Add a fake delay to make waiting noticeable.
- await new Promise(resolve => {
- setTimeout(resolve, 2000);
+---
+
+### Using with `useOptimistic` {/*using-with-useoptimistic*/}
+
+You can combine `useActionState` with [`useOptimistic`](/reference/react/useOptimistic) to show immediate UI feedback:
+
+
+
+
+```js src/App.js
+import { useActionState, startTransition, useOptimistic } from 'react';
+import { addToCart, removeFromCart } from './api';
+import Total from './Total';
+
+export default function Checkout() {
+ const [count, dispatchAction, isPending] = useActionState(updateCartAction, 0);
+ const [optimisticCount, setOptimisticCount] = useOptimistic(count);
+
+ function handleAdd() {
+ startTransition(() => {
+ setOptimisticCount(c => c + 1);
+ dispatchAction({ type: 'ADD' });
});
- return "Couldn't add to cart: the item is sold out.";
}
+
+ function handleRemove() {
+ startTransition(() => {
+ setOptimisticCount(c => c - 1);
+ dispatchAction({ type: 'REMOVE' });
+ });
+ }
+
+ return (
+