diff --git a/.gitignore b/.gitignore index ff88094de..92626a1e6 100644 --- a/.gitignore +++ b/.gitignore @@ -43,3 +43,6 @@ public/rss.xml # claude local settings .claude/*.local.* .claude/react/ + +# worktrees +.worktrees/ diff --git a/src/content/blog/2025/12/11/denial-of-service-and-source-code-exposure-in-react-server-components.md b/src/content/blog/2025/12/11/denial-of-service-and-source-code-exposure-in-react-server-components.md index 6845e2f2f..dc049c78c 100644 --- a/src/content/blog/2025/12/11/denial-of-service-and-source-code-exposure-in-react-server-components.md +++ b/src/content/blog/2025/12/11/denial-of-service-and-source-code-exposure-in-react-server-components.md @@ -106,7 +106,7 @@ See [this issue](https://github.com/facebook/react-native/issues/54772#issuecomm **CVEs:** [CVE-2026-23864](https://www.cve.org/CVERecord?id=CVE-2026-23864) **Base Score:** 7.5 (High) -**Date**: January 26, 2025 +**Date**: January 26, 2026 Security researchers discovered additional DoS vulnerabilities still exist in React Server Components. diff --git a/src/content/reference/react/Activity.md b/src/content/reference/react/Activity.md index b53064c2b..b79bed9e2 100644 --- a/src/content/reference/react/Activity.md +++ b/src/content/reference/react/Activity.md @@ -48,7 +48,7 @@ In this way, Activity can be thought of as a mechanism for rendering "background #### Caveats {/*caveats*/} - If an Activity is rendered inside of a [ViewTransition](/reference/react/ViewTransition), and it becomes visible as a result of an update caused by [startTransition](/reference/react/startTransition), it will activate the ViewTransition's `enter` animation. If it becomes hidden, it will activate its `exit` animation. -- An Activity that just renders text will not render anything rather than rendering hidden text, because there’s no corresponding DOM element to apply visibility changes to. For example, `` will not produce any output in the DOM for `const ComponentThatJustReturnsText = () => "Hello, World!"`. +- A *hidden* Activity that just renders text will not render anything rather than rendering hidden text, because there’s no corresponding DOM element to apply visibility changes to. For example, `` will not produce any output in the DOM for `const ComponentThatJustReturnsText = () => "Hello, World!"`. `` will render visible text. --- diff --git a/src/content/reference/react/hooks.md b/src/content/reference/react/hooks.md index 6dea3a0fd..ab48b644b 100644 --- a/src/content/reference/react/hooks.md +++ b/src/content/reference/react/hooks.md @@ -79,6 +79,9 @@ There are two rarely used variations of `useEffect` with differences in timing: * [`useLayoutEffect`](/reference/react/useLayoutEffect) fires before the browser repaints the screen. You can measure layout here. * [`useInsertionEffect`](/reference/react/useInsertionEffect) fires before React makes changes to the DOM. Libraries can insert dynamic CSS here. +You can also separate events from Effects: + +- [`useEffectEvent`](/reference/react/useEffectEvent) creates a non-reactive event to fire from any Effect hook. --- ## Performance Hooks {/*performance-hooks*/} diff --git a/src/content/reference/react/useActionState.md b/src/content/reference/react/useActionState.md index f83f6bdc7..ed17c24f0 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 ( -
- {state} - -
- ) +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 ( -
- {/* ... */} -
+
+

Checkout

+
+ Eras Tour Tickets + Qty: {count} +
+
+ +
+
+ +
+ ); +} +``` + +```js src/Total.js +const formatter = new Intl.NumberFormat('en-US', { + style: 'currency', + currency: 'USD', + minimumFractionDigits: 0, +}); + +export default function Total({quantity, isPending}) { + return ( +
+ Total + {isPending ? 'πŸŒ€ Updating...' : formatter.format(quantity * 9999)} +
); } ``` -`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 `
` as its `action` prop or call manually within `startTransition`. -3. A pending state that you can utilise while your action is processing. +.row { + display: flex; + justify-content: space-between; + align-items: center; +} -When the form is submitted, the action function that you provided will be called. Its return value will become the new current state of the form. +.row button { + margin-left: auto; + min-width: 150px; +} -The action that you provide will also receive a new first argument, namely the current state of the form. The first time the form is submitted, this will be the initial state you provided, while with subsequent submissions, it will be the return value from the last time the action was called. The rest of the arguments are the same as if `useActionState` had not been used. +.total { + font-weight: bold; +} -```js [[3, 1, "action"], [1, 1, "currentState"]] -function action(currentState, formData) { - // ... - return 'next state'; +hr { + width: 100%; + border: none; + border-top: 1px solid #ccc; + margin: 4px 0; +} + +button { + padding: 8px 16px; + cursor: pointer; } ``` - + + +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 ( - -

{itemTitle}

- - - {isPending ? "Loading..." : message} - +
+

Checkout

+
+ Eras Tour Tickets + + {isPending ? 'πŸŒ€' : count} + + + + + +
+
+ +
); } -export default function App() { +async function updateCartAction(prevCount, actionPayload) { + switch (actionPayload.type) { + case 'ADD': { + return await addToCart(prevCount); + } + case 'REMOVE': { + return await removeFromCart(prevCount); + } + } + return prevCount; +} +``` + +```js src/Total.js +const formatter = new Intl.NumberFormat('en-US', { + style: 'currency', + currency: 'USD', + minimumFractionDigits: 0, +}); + +export default function Total({quantity, isPending}) { return ( - <> - - - - ) +
+ Total + {isPending ? 'πŸŒ€ Updating...' : formatter.format(quantity * 9999)} +
+ ); +} +``` + +```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 ( +
+

Checkout

+
+ Eras Tour Tickets + + {isPending && 'πŸŒ€'} + {optimisticCount} + + + + + +
+
+ +
+ ); +} + +async function updateCartAction(prevCount, actionPayload) { + switch (actionPayload.type) { + case 'ADD': { + return await addToCart(prevCount); + } + case 'REMOVE': { + return await removeFromCart(prevCount); + } + } + return prevCount; +} +``` + +```js src/Total.js +const formatter = new Intl.NumberFormat('en-US', { + style: 'currency', + currency: 'USD', + minimumFractionDigits: 0, +}); + +export default function Total({quantity, isPending}) { + return ( +
+ Total + {isPending ? 'πŸŒ€ Updating...' : formatter.format(quantity * 9999)} +
+ ); +} +``` + +```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 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; } -form button { - margin-right: 12px; +.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; } ``` + - -#### Display structured information after submitting a form {/*display-structured-information-after-submitting-a-form*/} +`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 {/*using-with-action-props*/} + +When you pass the `dispatchAction` function to a component that exposes an [Action prop](/reference/react/useTransition#exposing-action-props-from-components), you don't need to call `startTransition` or `useOptimistic` yourself. -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. +This example shows using the `increaseAction` and `decreaseAction` props of a QuantityStepper component: ```js src/App.js -import { useActionState, useState } from "react"; -import { addToCart } from "./actions.js"; +import { useActionState } from 'react'; +import { addToCart, removeFromCart } from './api'; +import QuantityStepper from './QuantityStepper'; +import Total from './Total'; + +export default function Checkout() { + const [count, dispatchAction, isPending] = useActionState(updateCartAction, 0); + + function addAction() { + dispatchAction({type: 'ADD'}); + } + + function removeAction() { + dispatchAction({type: 'REMOVE'}); + } -function AddToCartForm({itemID, itemTitle}) { - const [formState, formAction] = useActionState(addToCart, {}); return ( -
-

{itemTitle}

- - - {formState?.success && -
- Added to cart! Your cart now has {formState.cartSize} items. -
- } - {formState?.success === false && -
- Failed to add to cart: {formState.message} -
- } -
+
+

Checkout

+
+ Eras Tour Tickets + +
+
+ +
); } -export default function App() { - return ( - <> - - - - ) +async function updateCartAction(prevCount, actionPayload) { + switch (actionPayload.type) { + case 'ADD': { + return await addToCart(prevCount); + } + case 'REMOVE': { + return await removeFromCart(prevCount); + } + } + return prevCount; } ``` -```js src/actions.js -"use server"; +```js src/QuantityStepper.js +import { startTransition, useOptimistic } from 'react'; -export async function addToCart(prevState, queryData) { - const itemID = queryData.get('itemID'); - if (itemID === "1") { - return { - success: true, - cartSize: 12, - }; - } else { - return { - success: false, - message: "The item is sold out.", - }; +export default function QuantityStepper({value, increaseAction, decreaseAction}) { + const [optimisticValue, setOptimisticValue] = useOptimistic(value); + const isPending = value !== optimisticValue; + function handleIncrease() { + startTransition(async () => { + setOptimisticValue(c => c + 1); + await increaseAction(); + }); + } + + function handleDecrease() { + startTransition(async () => { + setOptimisticValue(c => Math.max(0, c - 1)); + await decreaseAction(); + }); } + + return ( + + {isPending && 'πŸŒ€'} + {optimisticValue} + + + + + + ); +} +``` + +```js src/Total.js +const formatter = new Intl.NumberFormat('en-US', { + style: 'currency', + currency: 'USD', + minimumFractionDigits: 0, +}); + +export default function Total({quantity, isPending}) { + return ( +
+ Total + {isPending ? 'πŸŒ€ Updating...' : formatter.format(quantity * 9999)} +
+ ); } ``` -```css src/styles.css hidden -form { - border: solid 1px black; - margin-bottom: 24px; - padding: 12px +```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; +} -## Troubleshooting {/*troubleshooting*/} +.row { + display: flex; + justify-content: space-between; + align-items: center; +} -### My action can no longer read the submitted form data {/*my-action-can-no-longer-read-the-submitted-form-data*/} +.stepper { + display: flex; + align-items: center; + gap: 8px; +} -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. +.qty { + min-width: 20px; + text-align: center; +} -```js -function action(currentState, formData) { - // ... +.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. + +--- + +### Cancelling queued Actions {/*cancelling-queued-actions*/} + +You can use an `AbortController` to cancel pending Actions: + + + +```js src/App.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 }); + } + + return ( +
+

Checkout

+
+ Eras Tour Tickets + +
+
+ +
+ ); +} + +async function updateCartAction(prevCount, actionPayload) { + switch (actionPayload.type) { + case 'ADD': { + try { + return await addToCart(prevCount, { signal: actionPayload.signal }); + } catch (e) { + return prevCount + 1; + } + } + case 'REMOVE': { + try { + return await removeFromCart(prevCount, { signal: actionPayload.signal }); + } catch (e) { + return Math.max(0, prevCount - 1); + } + } + } + return prevCount; +} +``` + +```js src/QuantityStepper.js +import { startTransition, useOptimistic } from 'react'; + +export default function QuantityStepper({value, increaseAction, decreaseAction}) { + const [optimisticValue, setOptimisticValue] = useOptimistic(value); + const isPending = value !== optimisticValue; + function handleIncrease() { + startTransition(async () => { + setOptimisticValue(c => c + 1); + await increaseAction(); + }); + } + + function handleDecrease() { + startTransition(async () => { + setOptimisticValue(c => Math.max(0, c - 1)); + await decreaseAction(); + }); + } + + return ( + + {isPending && 'πŸŒ€'} + {optimisticValue} + + + + + + ); +} +``` + +```js src/Total.js +const formatter = new Intl.NumberFormat('en-US', { + style: 'currency', + currency: 'USD', + minimumFractionDigits: 0, +}); + +export default function Total({quantity, isPending}) { + return ( +
+ Total + {isPending ? 'πŸŒ€ Updating...' : formatter.format(quantity * 9999)} +
+ ); +} +``` + +```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 +.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; +} +``` + + + +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 `
` Action props {/*use-with-a-form*/} + +You can pass the `dispatchAction` function as the `action` prop to a ``. + +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`: + + + +```js src/App.js +import { useActionState, 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); + + async function formAction(formData) { + const type = formData.get('type'); + if (type === 'ADD') { + setOptimisticCount(c => c + 1); + } else { + setOptimisticCount(c => Math.max(0, c - 1)); + } + return dispatchAction(formData); + } + + return ( + +

Checkout

+
+ Eras Tour Tickets + + {isPending && 'πŸŒ€'} + {optimisticCount} + + + + + +
+
+ + + ); +} + +async function updateCartAction(prevCount, formData) { + const type = formData.get('type'); + switch (type) { + case 'ADD': { + return await addToCart(prevCount); + } + case 'REMOVE': { + return await removeFromCart(prevCount); + } + } + return prevCount; +} +``` + +```js src/Total.js +const formatter = new Intl.NumberFormat('en-US', { + style: 'currency', + currency: 'USD', + minimumFractionDigits: 0, +}); + +export default function Total({quantity, isPending}) { + return ( +
+ Total + {isPending ? 'πŸŒ€ Updating...' : formatter.format(quantity * 9999)} +
+ ); +} +``` + +```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; +} +``` + +
+ +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. + + + +When used with a [Server Function](/reference/rsc/server-functions), `useActionState` allows the server's response to be shown before hydration (when React attaches to server-rendered HTML) completes. You can also use the optional `permalink` parameter for progressive enhancement (allowing the form to work before JavaScript loads) on pages with dynamic content. This is typically handled by your framework for you. + + + +See the [`
`](/reference/react-dom/components/form#handle-form-submission-with-a-server-function) docs for more information on using Actions with forms. + +--- + +### Handling errors {/*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](/reference/react/Component#catching-rendering-errors-with-an-error-boundary) by rethrowing the error from the `useActionState` hook. + + + +```js src/App.js +import {useActionState, startTransition} from 'react'; +import {ErrorBoundary} from 'react-error-boundary'; +import {addToCart} from './api'; +import Total from './Total'; + +function Checkout() { + const [state, dispatchAction, isPending] = useActionState( + async (prevState, quantity) => { + const result = await addToCart(prevState.count, quantity); + if (result.error) { + // Return the error from the API as state + return {...prevState, error: `Could not add quanitiy ${quantity}: ${result.error}`}; + } + + if (!isPending) { + // Clear the error state for the first dispatch. + return {count: result.count, error: null}; + } + + // Return the new count, and any errors that happened. + return {count: result.count, error: prevState.error}; + + + }, + { + count: 0, + error: null, + } + ); + + function handleAdd(quantity) { + startTransition(() => { + dispatchAction(quantity); + }); + } + + return ( +
+

Checkout

+
+ Eras Tour Tickets + + {isPending && 'πŸŒ€ '}Qty: {state.count} + +
+
+ + + +
+ {state.error &&
{state.error}
} +
+ +
+ ); +} + + + +export default function App() { + return ( + ( +
+

Something went wrong

+

The action could not be completed.

+ +
+ )}> + + + ); +} +``` + +```js src/Total.js +const formatter = new Intl.NumberFormat('en-US', { + style: 'currency', + currency: 'USD', + minimumFractionDigits: 0, +}); + +export default function Total({quantity, isPending}) { + return ( +
+ Total + + {isPending ? 'πŸŒ€ Updating...' : formatter.format(quantity * 9999)} + +
+ ); +} +``` + +```js src/api.js hidden +export async function addToCart(count, quantity) { + await new Promise((resolve) => setTimeout(resolve, 1000)); + if (quantity > 5) { + return {error: 'Quantity not available'}; + } else if (isNaN(quantity)) { + throw new Error('Quantity must be a number'); + } + return {count: count + quantity}; +} +``` + +```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; +} + +.total { + font-weight: bold; +} + +hr { + width: 100%; + border: none; + border-top: 1px solid #ccc; + margin: 4px 0; +} + +button { + padding: 8px 16px; + cursor: pointer; +} + +.buttons { + display: flex; + gap: 8px; +} + +.error { + color: red; + font-size: 14px; +} +``` + +```json package.json hidden +{ + "dependencies": { + "react": "19.0.0", + "react-dom": "19.0.0", + "react-scripts": "^5.0.0", + "react-error-boundary": "4.0.3" + }, + "main": "/index.js" +} +``` + + + +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 {/*troubleshooting*/} + +### My `isPending` flag is not updating {/*ispending-not-updating*/} + +If you're calling `dispatchAction` manually (not through an Action prop), make sure you wrap the call in [`startTransition`](/reference/react/startTransition): + +```js +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 {/*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. + +```js {2,7} +// 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 {/*actions-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: + +```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 }; + } +} +``` + +--- + +### My state doesn't reset {/*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, 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 `` `action` prop, which resets automatically after submission. + +--- + +### I'm getting an error: "An async function with useActionState was called outside of a transition." {/*async-function-outside-transition*/} + +A common mistake is to forget to call `dispatchAction` from inside a Transition: + + + + +An async function with useActionState was called outside of a transition. This is likely not what you intended (for example, isPending will not update correctly). Either call the returned function inside startTransition, or pass it to an `action` or `formAction` prop. + + + + + +This error happens because `dispatchAction` must run inside a Transition: + +```js +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`](/reference/react/startTransition): + +```js +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: + +```js +function MyComponent() { + const [state, dispatchAction, isPending] = useActionState(myAsyncAction, null); + + // βœ… Correct: action prop wraps in a Transition for you + return ; +} +``` + +--- + +### I'm getting an error: "Cannot update action state while rendering" {/*cannot-update-during-render*/} + +You cannot call `dispatchAction` during render: + + + +Cannot update action state while rendering. + + + +This causes an infinite loop because calling `dispatchAction` schedules a state update, which triggers a re-render, which calls `dispatchAction` again. + +```js +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). diff --git a/src/content/reference/react/useEffectEvent.md b/src/content/reference/react/useEffectEvent.md index bfac4c48e..0b32a8379 100644 --- a/src/content/reference/react/useEffectEvent.md +++ b/src/content/reference/react/useEffectEvent.md @@ -4,91 +4,551 @@ title: useEffectEvent -`useEffectEvent` is a React Hook that lets you extract non-reactive logic from your Effects into a reusable function called an [Effect Event](/learn/separating-events-from-effects#declaring-an-effect-event). +`useEffectEvent` is a React Hook that lets you separate events from Effects. ```js -const onSomething = useEffectEvent(callback) +const onEvent = useEffectEvent(callback) ``` +--- + ## Reference {/*reference*/} ### `useEffectEvent(callback)` {/*useeffectevent*/} -Call `useEffectEvent` at the top level of your component to declare an Effect Event. Effect Events are functions you can call inside Effects, such as `useEffect`: +Call `useEffectEvent` at the top level of your component to create an Effect Event. -```js {4-6,11} +```js {4,6} import { useEffectEvent, useEffect } from 'react'; function ChatRoom({ roomId, theme }) { const onConnected = useEffectEvent(() => { showNotification('Connected!', theme); }); +} +``` + +Effect Events are a part of your Effect logic, but they behave more like an event handler. They always β€œsee” the latest values from render (like props and state) without re-synchronizing your Effect, so they're excluded from Effect dependencies. See [Separating Events from Effects](/learn/separating-events-from-effects#extracting-non-reactive-logic-out-of-effects) to learn more. + +[See more examples below.](#usage) + +#### Parameters {/*parameters*/} + +* `callback`: A function containing the logic for your Effect Event. The function can accept any number of arguments and return any value. When you call the returned Effect Event function, the `callback` always accesses the latest committed values from render at the time of the call. + +#### Returns {/*returns*/} + +`useEffectEvent` returns an Effect Event function with the same type signature as your `callback`. + +You can call this function inside `useEffect`, `useLayoutEffect`, `useInsertionEffect`, or from within other Effect Events in the same component. + +#### Caveats {/*caveats*/} + +* `useEffectEvent` 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 Effect Event into it. +* Effect Events can only be called from inside Effects or other Effect Events. Do not call them during rendering or pass them to other components or Hooks. The [`eslint-plugin-react-hooks`](/reference/eslint-plugin-react-hooks) linter enforces this restriction. +* Do not use `useEffectEvent` to avoid specifying dependencies in your Effect's dependency array. This hides bugs and makes your code harder to understand. Only use it for logic that is genuinely an event fired from Effects. +* Effect Event functions do not have a stable identity. Their identity intentionally changes on every render. + + + +#### Why are Effect Events not stable? {/*why-are-effect-events-not-stable*/} + +Unlike `set` functions from `useState` or refs, Effect Event functions do not have a stable identity. Their identity intentionally changes on every render: + +```js +// πŸ”΄ Wrong: including Effect Event in dependencies +useEffect(() => { + onSomething(); +}, [onSomething]); // ESLint will warn about this +``` + +This is a deliberate design choice. Effect Events are meant to be called only from within Effects in the same component. Since you can only call them locally and cannot pass them to other components or include them in dependency arrays, a stable identity would serve no purpose, and would actually mask bugs. + +The non-stable identity acts as a runtime assertion: if your code incorrectly depends on the function identity, you'll see the Effect re-running on every render, making the bug obvious. + +This design reinforces that Effect Events conceptually belong to a particular effect, and are not a general purpose API to opt-out of reactivity. + + + +--- + +## Usage {/*usage*/} + + +### Using an event in an Effect {/*using-an-event-in-an-effect*/} + +Call `useEffectEvent` at the top level of your component to create an *Effect Event*: + + +```js [[1, 1, "onConnected"]] +const onConnected = useEffectEvent(() => { + if (!muted) { + showNotification('Connected!'); + } +}); +``` + +`useEffectEvent` accepts an `event callback` and returns an Effect Event. The Effect Event is a function that can be called inside of Effects without re-connecting the Effect: + +```js [[1, 3, "onConnected"]] +useEffect(() => { + const connection = createConnection(roomId); + connection.on('connected', onConnected); + connection.connect(); + return () => { + connection.disconnect(); + } +}, [roomId]); +``` + +Since `onConnected` is an Effect Event, `muted` and `onConnect` are not in the Effect dependencies. + + + +##### Don't use Effect Events to skip dependencies {/*pitfall-skip-dependencies*/} + +It might be tempting to use `useEffectEvent` to avoid listing dependencies that you think are "unnecessary." However, this hides bugs and makes your code harder to understand: + +```js +// πŸ”΄ Wrong: Using Effect Events to hide dependencies +const logVisit = useEffectEvent(() => { + log(pageUrl); +}); + +useEffect(() => { + logVisit() +}, []); // Missing pageUrl means you miss logs +``` + +If a value should cause your Effect to re-run, keep it as a dependency. Only use Effect Events for logic that genuinely should not re-trigger your Effect. + +See [Separating Events from Effects](/learn/separating-events-from-effects) to learn more. + + + +--- + +### Using a timer with latest values {/*using-a-timer-with-latest-values*/} + +When you use `setInterval` or `setTimeout` in an Effect, you often want to read the latest values from render without restarting the timer whenever those values change. + +This counter increments `count` by the current `increment` value every second. The `onTick` Effect Event reads the latest `count` and `increment` without causing the interval to restart: + + + +```js +import { useState, useEffect, useEffectEvent } from 'react'; + +export default function Timer() { + const [count, setCount] = useState(0); + const [increment, setIncrement] = useState(1); + + const onTick = useEffectEvent(() => { + setCount(count + increment); + }); + + useEffect(() => { + const id = setInterval(() => { + onTick(); + }, 1000); + return () => { + clearInterval(id); + }; + }, []); + + return ( + <> +

+ Counter: {count} + +

+
+

+ Every second, increment by: + + {increment} + +

+ + ); +} +``` + +```css +button { margin: 10px; } +``` + + + +Try changing the increment value while the timer is running. The counter immediately uses the new increment value, but the timer keeps ticking smoothly without restarting. + +--- + +### Using an event listener with latest values {/*using-an-event-listener-with-latest-values*/} + +When you set up an event listener in an Effect, you often need to read the latest values from render in the callback. Without `useEffectEvent`, you would need to include the values in your dependencies, causing the listener to be removed and re-added on every change. + +This example shows a dot that follows the cursor, but only when "Can move" is checked. The `onMove` Effect Event always reads the latest `canMove` value without re-running the Effect: + + + +```js +import { useState, useEffect, useEffectEvent } from 'react'; + +export default function App() { + const [position, setPosition] = useState({ x: 0, y: 0 }); + const [canMove, setCanMove] = useState(true); + + const onMove = useEffectEvent(e => { + if (canMove) { + setPosition({ x: e.clientX, y: e.clientY }); + } + }); useEffect(() => { - const connection = createConnection(serverUrl, roomId); + window.addEventListener('pointermove', onMove); + return () => window.removeEventListener('pointermove', onMove); + }, []); + + return ( + <> + +
+
+ + ); +} +``` + +```css +body { + height: 200px; +} +``` + + + +Toggle the checkbox and move your cursor. The dot responds immediately to the checkbox state, but the event listener is only set up once when the component mounts. + +--- + +### Avoid reconnecting to external systems {/*showing-a-notification-without-reconnecting*/} + +A common use case for `useEffectEvent` is when you want to do something in response to an Effect, but that "something" depends on a value you don't want to react to. + +In this example, a chat component connects to a room and shows a notification when connected. The user can mute notifications with a checkbox. However, you don't want to reconnect to the chat room every time the user changes the settings: + + + +```json package.json hidden +{ + "dependencies": { + "react": "latest", + "react-dom": "latest", + "react-scripts": "latest", + "toastify-js": "1.12.0" + }, + "scripts": { + "start": "react-scripts start", + "build": "react-scripts build", + "test": "react-scripts test --env=jsdom", + "eject": "react-scripts eject" + } +} +``` + +```js +import { useState, useEffect, useEffectEvent } from 'react'; +import { createConnection } from './chat.js'; +import { showNotification } from './notifications.js'; + +function ChatRoom({ roomId, muted }) { + const onConnected = useEffectEvent((roomId) => { + console.log('βœ… Connected to ' + roomId + ' (muted: ' + muted + ')'); + if (!muted) { + showNotification('Connected to ' + roomId); + } + }); + + useEffect(() => { + const connection = createConnection(roomId); + console.log('⏳ Connecting to ' + roomId + '...'); connection.on('connected', () => { - onConnected(); + onConnected(roomId); }); connection.connect(); - return () => connection.disconnect(); + return () => { + console.log('❌ Disconnected from ' + roomId); + connection.disconnect(); + } }, [roomId]); - // ... + return

Welcome to the {roomId} room!

; +} + +export default function App() { + const [roomId, setRoomId] = useState('general'); + const [muted, setMuted] = useState(false); + return ( + <> + + +
+ + + ); } ``` -[See more examples below.](#usage) +```js src/chat.js +const serverUrl = 'https://localhost:1234'; + +export function createConnection(roomId) { + // A real implementation would actually connect to the server + let connectedCallback; + let timeout; + return { + connect() { + timeout = setTimeout(() => { + if (connectedCallback) { + connectedCallback(); + } + }, 100); + }, + on(event, callback) { + if (connectedCallback) { + throw Error('Cannot add the handler twice.'); + } + if (event !== 'connected') { + throw Error('Only "connected" event is supported.'); + } + connectedCallback = callback; + }, + disconnect() { + clearTimeout(timeout); + } + }; +} +``` -#### Parameters {/*parameters*/} +```js src/notifications.js +import Toastify from 'toastify-js'; +import 'toastify-js/src/toastify.css'; + +export function showNotification(message, theme) { + Toastify({ + text: message, + duration: 2000, + gravity: 'top', + position: 'right', + style: { + background: theme === 'dark' ? 'black' : 'white', + color: theme === 'dark' ? 'white' : 'black', + }, + }).showToast(); +} +``` -- `callback`: A function containing the logic for your Effect Event. When you define an Effect Event with `useEffectEvent`, the `callback` always accesses the latest values from props and state when it is invoked. This helps avoid issues with stale closures. +```css +label { display: block; margin-top: 10px; } +``` -#### Returns {/*returns*/} + -Returns an Effect Event function. You can call this function inside `useEffect`, `useLayoutEffect`, or `useInsertionEffect`. +Try switching rooms. The chat reconnects and shows a notification. Now mute the notifications. Since `muted` is read inside the Effect Event rather than the Effect, the chat stays connected. -#### Caveats {/*caveats*/} +--- -- **Only call inside Effects:** Effect Events should only be called within Effects. Define them just before the Effect that uses them. Do not pass them to other components or hooks. The [`eslint-plugin-react-hooks`](/reference/eslint-plugin-react-hooks) linter (version 6.1.1 or higher) will enforce this restriction to prevent calling Effect Events in the wrong context. -- **Not a dependency shortcut:** Do not use `useEffectEvent` to avoid specifying dependencies in your Effect's dependency array. This can hide bugs and make your code harder to understand. Prefer explicit dependencies or use refs to compare previous values if needed. -- **Use for non-reactive logic:** Only use `useEffectEvent` to extract logic that does not depend on changing values. +### Using Effect Events in custom Hooks {/*using-effect-events-in-custom-hooks*/} -___ +You can use `useEffectEvent` inside your own custom Hooks. This lets you create reusable Hooks that encapsulate Effects while keeping some values non-reactive: -## Usage {/*usage*/} + -### Reading the latest props and state {/*reading-the-latest-props-and-state*/} +```js +import { useState, useEffect, useEffectEvent } from 'react'; -Typically, when you access a reactive value inside an Effect, you must include it in the dependency array. This makes sure your Effect runs again whenever that value changes, which is usually the desired behavior. +function useInterval(callback, delay) { + const onTick = useEffectEvent(callback); -But in some cases, you may want to read the most recent props or state inside an Effect without causing the Effect to re-run when those values change. + useEffect(() => { + if (delay === null) { + return; + } + const id = setInterval(() => { + onTick(); + }, delay); + return () => clearInterval(id); + }, [delay]); +} + +function Counter({ incrementBy }) { + const [count, setCount] = useState(0); + + useInterval(() => { + setCount(c => c + incrementBy); + }, 1000); + + return ( +
+

Count: {count}

+

Incrementing by {incrementBy} every second

+
+ ); +} -To [read the latest props or state](/learn/separating-events-from-effects#reading-latest-props-and-state-with-effect-events) in your Effect, without making those values reactive, include them in an Effect Event. +export default function App() { + const [incrementBy, setIncrementBy] = useState(1); + + return ( + <> + +
+ + + ); +} +``` -```js {7-9,12} -import { useEffect, useContext, useEffectEvent } from 'react'; +```css +label { display: block; margin-bottom: 8px; } +``` -function Page({ url }) { - const { items } = useContext(ShoppingCartContext); - const numberOfItems = items.length; + - const onNavigate = useEffectEvent((visitedUrl) => { - logVisit(visitedUrl, numberOfItems); +In this example, `useInterval` is a custom Hook that sets up an interval. The `callback` passed to it is wrapped in an Effect Event, so the interval does not reset even if a new `callback` is passed in every render. + +--- + +## Troubleshooting {/*troubleshooting*/} + +### I'm getting an error: "A function wrapped in useEffectEvent can't be called during rendering" {/*cant-call-during-rendering*/} + +This error means you're calling an Effect Event function during the render phase of your component. Effect Events can only be called from inside Effects or other Effect Events. + +```js +function MyComponent({ data }) { + const onLog = useEffectEvent(() => { + console.log(data); }); + // πŸ”΄ Wrong: calling during render + onLog(); + + // βœ… Correct: call from an Effect useEffect(() => { - onNavigate(url); - }, [url]); + onLog(); + }, []); - // ... + return
{data}
; } ``` -In this example, the Effect should re-run after a render when `url` changes (to log the new page visit), but it should **not** re-run when `numberOfItems` changes. By wrapping the logging logic in an Effect Event, `numberOfItems` becomes non-reactive. It's always read from the latest value without triggering the Effect. +If you need to run logic during render, don't wrap it in `useEffectEvent`. Call the logic directly or move it into an Effect. + +--- + +### I'm getting a lint error: "Functions returned from useEffectEvent must not be included in the dependency array" {/*effect-event-in-deps*/} + +If you see a warning like "Functions returned from `useEffectEvent` must not be included in the dependency array", remove the Effect Event from your dependencies: + +```js +const onSomething = useEffectEvent(() => { + // ... +}); + +// πŸ”΄ Wrong: Effect Event in dependencies +useEffect(() => { + onSomething(); +}, [onSomething]); + +// βœ… Correct: no Effect Event in dependencies +useEffect(() => { + onSomething(); +}, []); +``` + +Effect Events are designed to be called from Effects without being listed as dependencies. The linter enforces this because the function identity is [intentionally not stable](#why-are-effect-events-not-stable). Including it would cause your Effect to re-run on every render. -You can pass reactive values like `url` as arguments to the Effect Event to keep them reactive while accessing the latest non-reactive values inside the event. +--- + +### I'm getting a lint error: "... is a function created with useEffectEvent, and can only be called from Effects" {/*effect-event-called-outside-effect*/} + +If you see a warning like "... is a function created with React Hook `useEffectEvent`, and can only be called from Effects and Effect Events", you're calling the function from the wrong place: + +```js +const onSomething = useEffectEvent(() => { + console.log(value); +}); + +// πŸ”΄ Wrong: calling from event handler +function handleClick() { + onSomething(); +} + +// πŸ”΄ Wrong: passing to child component +return ; + +// βœ… Correct: calling from Effect +useEffect(() => { + onSomething(); +}, []); +``` +Effect Events are specifically designed to be used in Effects local to the component they're defined in. If you need a callback for event handlers or to pass to children, use a regular function or `useCallback` instead. \ No newline at end of file diff --git a/src/content/reference/react/useOptimistic.md b/src/content/reference/react/useOptimistic.md index 250e43a3c..702f9936c 100644 --- a/src/content/reference/react/useOptimistic.md +++ b/src/content/reference/react/useOptimistic.md @@ -110,7 +110,7 @@ This state is called the "optimistic" because it is used to immediately present 4. **(Optional) wait for Suspense**: If `newValue` suspends, React continues showing `'b'`. -5. **Single render commit**: Finally, the `newValue` is commits for `value` and `optimistic`. +5. **Single render commit**: Finally, the `newValue` commits for `value` and `optimistic`. There's no extra render to "clear" the optimistic state. The optimistic and real state converge in the same render when the Transition completes. @@ -118,7 +118,7 @@ There's no extra render to "clear" the optimistic state. The optimistic and real #### Optimistic state is temporary {/*optimistic-state-is-temporary*/} -Optimistic state is only renders while an Action is in progress, otherwise `value` is rendered. +Optimistic state only renders while an Action is in progress, otherwise `value` is rendered. If `saveChanges` returned `'c'`, then both `value` and `optimistic` will be `'c'`, not `'b'`. @@ -403,7 +403,7 @@ export default function App() { } if (optimisticIsLiked !== isLiked) { - console.log('βœ… rendering optmistic state: ' + optimisticIsLiked); + console.log('βœ… rendering optimistic state: ' + optimisticIsLiked); } else { console.log('βœ… rendering real value: ' + optimisticIsLiked); } @@ -1061,7 +1061,7 @@ If the values are not equal, there's a Transition in progress. 2. **Add a `useTransition`** -``` +```js const [isPending, startTransition] = useTransition(); const [optimistic, setOptimistic] = useOptimistic(value); @@ -1071,9 +1071,9 @@ startTransition(() => { }) ``` -Since `useTransition` uses `useOptimsitic` for `isPending` under the hood, this is equivalent to option 1. +Since `useTransition` uses `useOptimistic` for `isPending` under the hood, this is equivalent to option 1. -3**Add a `pending` flag in your reducer** +3. **Add a `pending` flag in your reducer** ```js const [optimistic, addOptimistic] = useOptimistic( @@ -1081,3 +1081,5 @@ const [optimistic, addOptimistic] = useOptimistic( (state, newItem) => [...state, { ...newItem, isPending: true }] ); ``` + +Since each optimistic item has its own flag, you can show loading state for individual items. diff --git a/src/content/reference/rules/components-and-hooks-must-be-pure.md b/src/content/reference/rules/components-and-hooks-must-be-pure.md index 2937dc210..973561c22 100644 --- a/src/content/reference/rules/components-and-hooks-must-be-pure.md +++ b/src/content/reference/rules/components-and-hooks-must-be-pure.md @@ -28,7 +28,7 @@ Concretely, this means that rendering logic can be run multiple times in a way t React is declarative: you tell React _what_ to render, and React will figure out _how_ best to display it to your user. To do this, React has a few phases where it runs your code. You don't need to know about all of these phases to use React well. But at a high level, you should know about what code runs in _render_, and what runs outside of it. -_Rendering_ refers to calculating what the next version of your UI should look like. After rendering, [Effects](/reference/react/useEffect) are _flushed_ (meaning they are run until there are no more left) and may update the calculation if the Effects have impacts on layout. React takes this new calculation and compares it to the calculation used to create the previous version of your UI, then _commits_ just the minimum changes needed to the [DOM](https://developer.mozilla.org/en-US/docs/Web/API/Document_Object_Model) (what your user actually sees) to catch it up to the latest version. +_Rendering_ refers to calculating what the next version of your UI should look like. After rendering, React takes this new calculation and compares it to the calculation used to create the previous version of your UI. Then React commits just the minimum changes needed to the [DOM](https://developer.mozilla.org/en-US/docs/Web/API/Document_Object_Model) (what your user actually sees) to apply the changes. Finally, [Effects](/learn/synchronizing-with-effects) are flushed (meaning they are run until there are no more left). For more detailed information see the docs for [Render](/learn/render-and-commit) and [Commit and Effect Hooks](/reference/react/hooks#effect-hooks).