diff --git a/src/content/reference/react/useActionState.md b/src/content/reference/react/useActionState.md
index f83f6bdc710..dfadcbe5f00 100644
--- a/src/content/reference/react/useActionState.md
+++ b/src/content/reference/react/useActionState.md
@@ -4,269 +4,1493 @@ 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?);
```
+
+
+---
+
+## Reference {/*reference*/}
+
+### `useActionState(reducerAction, initialState, permalink?)` {/*useactionstate*/}
+
+Call `useActionState` at the top level of your component to create state for the result of an Action.
+
+```js
+import { useActionState } from 'react';
+
+function reducerAction(previousState, actionPayload) {
+ // ...
+}
+
+function MyCart({initialState}) {
+ const [state, dispatchAction, isPending] = useActionState(reducerAction, initialState);
+ // ...
+}
+```
+
+[See more examples below.](#usage)
+
+#### Parameters {/*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](/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 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](/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*/}
+
+* `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, allowing each `reducerAction` to use the result of the previous Action.
+* 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.
+
-In earlier React Canary versions, this API was part of React DOM and called `useFormState`.
+`dispatchAction` must be called within a Transition.
+
+You can wrap it in [`startTransition`](/reference/react/startTransition), or pass it to an [Action prop](/reference/react/useTransition#exposing-action-props-from-components).
+---
-
+### `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 available for the current call.
+
+#### Parameters {/*reduceraction-parameters*/}
+
+* `previousState`: The current 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.
+
+
+
+#### 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.
+
+
---
-## Reference {/*reference*/}
+## Usage {/*usage*/}
-### `useActionState(action, initialState, permalink?)` {/*useactionstate*/}
+### Adding state to an Action {/*adding-state-to-an-action*/}
-{/* TODO T164397693: link to actions documentation once it exists */}
+Call `useActionState` at the top level of your component to create state for the result of an Action.
-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.
+```js [[1, 7, "count"], [2, 7, "dispatchAction"], [3, 7, "isPending"]]
+import { useActionState } from 'react';
-```js
-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.
+
+
+
+```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();
+ });
+ }
-async function increment(previousState, formData) {
- return previousState + 1;
+ return (
+
+ );
}
```
-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.
+```js src/api.js
+export async function addToCart(count) {
+ await new Promise(resolve => setTimeout(resolve, 1000));
+ return count + 1;
+}
-If used with a Server Function, `useActionState` allows the server's response from submitting the form to be shown even before hydration has completed.
+export async function removeFromCart(count) {
+ await new Promise(resolve => setTimeout(resolve, 1000));
+ return Math.max(0, count - 1);
+}
+```
-[See more examples below.](#usage)
+```css
+.checkout {
+ display: flex;
+ flex-direction: column;
+ gap: 12px;
+ padding: 16px;
+ border: 1px solid #ccc;
+ border-radius: 8px;
+ font-family: system-ui;
+}
-#### Parameters {/*parameters*/}
+.checkout h2 {
+ margin: 0 0 8px 0;
+}
-* `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.
+.row {
+ display: flex;
+ justify-content: space-between;
+ align-items: center;
+}
-{/* TODO T164397693: link to serializable values docs once it exists */}
+.row button {
+ margin-left: auto;
+ min-width: 150px;
+}
-#### Returns {/*returns*/}
+.total {
+ font-weight: bold;
+}
-`useActionState` returns an array with the following values:
+hr {
+ width: 100%;
+ border: none;
+ border-top: 1px solid #ccc;
+ margin: 4px 0;
+}
-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.
+button {
+ padding: 8px 16px;
+ cursor: pointer;
+}
+```
-#### Caveats {/*caveats*/}
+
+
+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.
+
+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`.
-* 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`.
+
---
-## Usage {/*usage*/}
+### Using multiple Action types {/*using-multiple-action-types*/}
-### Using information returned by a form action {/*using-information-returned-by-a-form-action*/}
+To handle multiple types, you can pass an argument to `dispatchAction`.
-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.
+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 [[1, 5, "state"], [2, 5, "formAction"], [3, 5, "action"], [4, 5, "null"], [2, 8, "formAction"]]
-import { useActionState } from 'react';
-import { action } from './actions.js';
+
+
+```js src/App.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 MyComponent() {
- const [state, formAction] = useActionState(action, null);
- // ...
return (
-
+
);
}
```
-`useActionState` returns an array with the following items:
+```js src/api.js hidden
+export async function addToCart(count) {
+ await new Promise(resolve => setTimeout(resolve, 1000));
+ return count + 1;
+}
-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 `
+
+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.
+
+
-#### Display form errors {/*display-form-errors*/}
+---
+
+### Using with `useOptimistic` {/*using-with-useoptimistic*/}
+
+You can combine `useActionState` with [`useOptimistic`](/reference/react/useOptimistic) to show immediate UI feedback:
-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`.
```js src/App.js
-import { useActionState, useState } from "react";
-import { addToCart } from "./actions.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' });
+ });
+ }
+
+ function handleRemove() {
+ startTransition(() => {
+ setOptimisticCount(c => c - 1);
+ 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;
}
-form button {
- margin-right: 12px;
+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;
+}
+```
+
-
+Since `` 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.
+
+---
-#### Display structured information after submitting a form {/*display-structured-information-after-submitting-a-form*/}
+### Cancelling queued Actions {/*cancelling-queued-actions*/}
-The return value from a Server Function can be any serializable value. For example, it could be an object that includes a boolean indicating whether the action was successful, an error message, or updated information.
+You can use an `AbortController` to cancel pending Actions:
```js src/App.js
-import { useActionState, useState } from "react";
-import { addToCart } from "./actions.js";
+import { useActionState, useRef } from 'react';
+import { addToCart, removeFromCart } from './api';
+import QuantityStepper from './QuantityStepper';
+import Total from './Total';
+
+export default function Checkout() {
+ const abortRef = useRef(null);
+ const [count, dispatchAction, isPending] = useActionState(updateCartAction, 0);
+
+ async function addAction() {
+ if (abortRef.current) {
+ abortRef.current.abort();
+ }
+ abortRef.current = new AbortController();
+ await dispatchAction({ type: 'ADD', signal: abortRef.current.signal });
+ }
+
+ async function removeAction() {
+ if (abortRef.current) {
+ abortRef.current.abort();
+ }
+ abortRef.current = new AbortController();
+ await dispatchAction({ type: 'REMOVE', signal: abortRef.current.signal });
+ }
-function AddToCartForm({itemID, itemTitle}) {
- const [formState, formAction] = useActionState(addToCart, {});
return (
-
+
+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.
+
+
+
+Aborting an Action isn't always safe.
+
+For example, if the Action performs a mutation (like writing to a database), aborting the network request doesn't undo the server-side change. This is why `useActionState` doesn't abort by default. It's only safe when you know the side effect can be safely ignored or retried.
+
+
+
+---
+
+### Using with `