From 54c057e3142337526ab1dd8db69aa85858dce6a3 Mon Sep 17 00:00:00 2001 From: Rick Hanlon Date: Thu, 29 Jan 2026 15:56:48 -0500 Subject: [PATCH 1/2] claude update for useEffectEvent --- src/content/reference/react/useEffectEvent.md | 516 +++++++++++++++++- 1 file changed, 502 insertions(+), 14 deletions(-) diff --git a/src/content/reference/react/useEffectEvent.md b/src/content/reference/react/useEffectEvent.md index bfac4c48e89..e5fe7ffb63f 100644 --- a/src/content/reference/react/useEffectEvent.md +++ b/src/content/reference/react/useEffectEvent.md @@ -4,7 +4,7 @@ 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 extract non-reactive logic from your Effects into a reusable function called an [*Effect Event*](/learn/separating-events-from-effects#declaring-an-effect-event). ```js const onSomething = useEffectEvent(callback) @@ -14,6 +14,8 @@ const onSomething = useEffectEvent(callback) +--- + ## Reference {/*reference*/} ### `useEffectEvent(callback)` {/*useeffectevent*/} @@ -45,19 +47,45 @@ function ChatRoom({ roomId, theme }) { #### Parameters {/*parameters*/} -- `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. +* `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 values from props and state at the time of the call. This helps avoid issues with stale closures. #### Returns {/*returns*/} -Returns an Effect Event function. You can call this function inside `useEffect`, `useLayoutEffect`, or `useInsertionEffect`. +`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*/} -- **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. +* `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 (version 6.1.1 or higher) enforces this restriction. +* Calling an Effect Event during rendering will throw an error: `"A function wrapped in useEffectEvent can't be called during rendering."` +* Do not include Effect Events in your Effect's dependency array. The function identity is intentionally non-stable, and including it would cause unnecessary Effect re-runs. The linter will warn if you try to do this. +* React does not preserve the `this` binding when you pass object methods to `useEffectEvent`. If you need to preserve `this`, bind the method first or use an arrow function wrapper. +* 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 genuinely should not re-trigger your Effect. + + + +#### Why is the function identity intentionally non-stable? {/*why-non-stable-identity*/} + +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 +``` + +Never include an Effect Event in your dependency array. The linter will warn you if you try. + +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 could actually mask bugs. + +If the identity were stable, you might accidentally include an Effect Event in a dependency array without the linter catching it. 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 the rule that Effect Events are "escape hatches" for reading the latest values, not general-purpose callbacks to be passed around. + + + +--- ## Usage {/*usage*/} @@ -69,26 +97,486 @@ But in some cases, you may want to read the most recent props or state inside an 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. -```js {7-9,12} -import { useEffect, useContext, useEffectEvent } from 'react'; + + +```js +import { useState, useEffect, useEffectEvent } from 'react'; function Page({ url }) { - const { items } = useContext(ShoppingCartContext); - const numberOfItems = items.length; + const [items, setItems] = useState([ + { id: 1, name: 'Apples' }, + { id: 2, name: 'Oranges' } + ]); const onNavigate = useEffectEvent((visitedUrl) => { - logVisit(visitedUrl, numberOfItems); + console.log('Visited:', visitedUrl, 'with', items.length, 'items in cart'); }); useEffect(() => { onNavigate(url); }, [url]); - // ... + return ( + <> +

Page: {url}

+

Items in cart: {items.length}

+ + + ); +} + +export default function App() { + const [url, setUrl] = useState('/home'); + + return ( + <> + +
+ + + ); } ``` -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. +```css +nav button { margin-right: 8px; } +``` + + + +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 `items` changes. By wrapping the logging logic in an Effect Event, `items.length` becomes non-reactive. The Effect Event always reads the latest value without triggering the Effect. + +Try clicking "Add item" and notice that no log appears. Then click a navigation button—the log appears and shows the current number of items. 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. + + +##### 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 onFetch = useEffectEvent(() => { + fetchData(userId); // userId should trigger refetch! +}); + +useEffect(() => { + onFetch(); +}, []); // Missing userId means stale data +``` + +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—like showing a notification in the current theme while connecting to a server. + + + +--- + +### Connecting to a chat room {/*connecting-to-a-chat-room*/} + +This example shows the primary use case for `useEffectEvent`: connecting to an external system where you want to react to some changes but not others. + +In this chat room example, the Effect connects to a chat server based on `roomId`. When the user changes the theme, you want to show a notification in the current theme color—but you don't want to reconnect to the server because the theme changed. + + + +#### Reading latest theme without reconnecting {/*reading-latest-theme*/} + +Change the room and notice the console logs showing connection and disconnection. Then change the theme—the notification uses the current theme, but no reconnection happens. + + + +```js +import { useState, useEffect, useEffectEvent } from 'react'; + +function ChatRoom({ roomId, theme }) { + const onConnected = useEffectEvent(() => { + console.log('✅ Connected to ' + roomId + ' (theme: ' + theme + ')'); + }); + + useEffect(() => { + console.log('⏳ Connecting to ' + roomId + '...'); + const id = setTimeout(() => { + onConnected(); + }, 1000); + return () => { + console.log('❌ Disconnected from ' + roomId); + clearTimeout(id); + }; + }, [roomId]); + + return

Welcome to the {roomId} room!

; +} + +export default function App() { + const [roomId, setRoomId] = useState('general'); + const [theme, setTheme] = useState('light'); + + return ( + <> + + +
+ + + ); +} +``` + +```css +label { display: block; margin-bottom: 8px; } +``` + + + + + +#### With muted notifications {/*with-muted-notifications*/} + +This example adds a `muted` state that controls whether the Effect Event shows notifications. The Effect Event reads the latest `muted` value without re-triggering the connection. + + + +```js +import { useState, useEffect, useEffectEvent } from 'react'; + +function ChatRoom({ roomId, theme, muted }) { + const onConnected = useEffectEvent(() => { + if (!muted) { + console.log('✅ Connected to ' + roomId + ' (theme: ' + theme + ')'); + } else { + console.log('✅ Connected to ' + roomId + ' (muted)'); + } + }); + + useEffect(() => { + console.log('⏳ Connecting to ' + roomId + '...'); + const id = setTimeout(() => { + onConnected(); + }, 1000); + return () => { + console.log('❌ Disconnected from ' + roomId); + clearTimeout(id); + }; + }, [roomId]); + + return

Welcome to the {roomId} room!

; +} + +export default function App() { + const [roomId, setRoomId] = useState('general'); + const [theme, setTheme] = useState('light'); + const [muted, setMuted] = useState(false); + + return ( + <> + + + +
+ + + ); +} +``` + +```css +label { display: block; margin-bottom: 8px; } +``` + + + + + + + +--- + +### Passing reactive values to Effect Events {/*passing-reactive-values-to-effect-events*/} + +You can pass arguments to your Effect Event function. This is useful when you have a reactive value that should trigger your Effect, but you also want to use that value inside the Effect Event along with other non-reactive values. + + + +```js +import { useState, useEffect, useEffectEvent } from 'react'; + +function Analytics({ url, userId }) { + const [sessionDuration, setSessionDuration] = useState(0); + + useEffect(() => { + const id = setInterval(() => { + setSessionDuration(d => d + 1); + }, 1000); + return () => clearInterval(id); + }, []); + + const onPageView = useEffectEvent((visitedUrl) => { + // visitedUrl is passed as argument - reactive + // userId and sessionDuration are read from closure - non-reactive + console.log('Page view:', visitedUrl); + console.log(' User:', userId); + console.log(' Session duration:', sessionDuration, 'seconds'); + }); + + useEffect(() => { + onPageView(url); + }, [url]); + + return ( +
+

Analytics for: {url}

+

User: {userId}

+

Session: {sessionDuration}s

+
+ ); +} + +export default function App() { + const [url, setUrl] = useState('/home'); + const [userId, setUserId] = useState('user-123'); + + return ( + <> +
+ + + +
+
+ +
+
+ + + ); +} +``` + +```css +button { margin-right: 8px; margin-bottom: 8px; } +``` + + + +In this example: +- `url` is passed as an argument to `onPageView`. This keeps it reactive—when `url` changes, the Effect runs again and calls `onPageView` with the new URL. +- `userId` and `sessionDuration` are read from closure inside the Effect Event. They're non-reactive—changing them doesn't re-run the Effect, but `onPageView` always sees their latest values when called. + +Try clicking "Change user" or waiting for the session timer—no log appears. Then click a navigation button—the log shows the current user and session duration. + +--- + +### 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. + + + +```js +import { useState, useEffect, useEffectEvent } from 'react'; + +function useInterval(callback, delay) { + const onTick = useEffectEvent(callback); + + 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

+
+ ); +} + +export default function App() { + const [incrementBy, setIncrementBy] = useState(1); + + return ( + <> + +
+ + + ); +} +``` + +```css +label { display: block; margin-bottom: 8px; } +``` + + + +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 is set up once when the component mounts (or when `delay` changes). +- Changing `incrementBy` doesn't restart the interval, but the callback always uses the latest value. + + + +Effect Events are designed to be called locally within the same component or Hook. Do not pass Effect Event functions to other components or Hooks—the linter will warn if you try. If you need to share event logic across components, consider lifting the Effect up or using a different pattern. + + + +--- + +## 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(() => { + onLog(); + }, []); + + return
{data}
; +} +``` + +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 non-stable—including it would cause your Effect to re-run on every render. + +--- + +### I'm getting a lint error: "onSomething is a function created with useEffectEvent, and can only be called from Effects" {/*effect-event-called-outside-effect*/} + +If you see a warning like "`onSomething` 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 read the latest values inside Effects. If you need a callback for event handlers or to pass to children, use a regular function or `useCallback` instead. + +--- + +### I'm seeing stale values when using Effect Events with `memo()` {/*stale-values-with-memo*/} + +There was a known bug in React where `useEffectEvent` could see stale closure values when used inside components wrapped with `memo()` or `forwardRef()`. This bug affected some React 19 versions. + +**Status:** React fixed this bug in [PR #34831](https://github.com/facebook/react/pull/34831). + +**Solution:** Update to the latest React version. If you can't update immediately, you can work around this by removing `memo()` temporarily or by restructuring your component to avoid the problematic pattern. \ No newline at end of file From 65bbdb02241a46a743c61743b3b31671cfb6310d Mon Sep 17 00:00:00 2001 From: Rick Hanlon Date: Thu, 29 Jan 2026 21:07:50 -0500 Subject: [PATCH 2/2] human edits --- src/content/reference/react/useEffectEvent.md | 492 +++++++++--------- 1 file changed, 232 insertions(+), 260 deletions(-) diff --git a/src/content/reference/react/useEffectEvent.md b/src/content/reference/react/useEffectEvent.md index e5fe7ffb63f..50248c85a9b 100644 --- a/src/content/reference/react/useEffectEvent.md +++ b/src/content/reference/react/useEffectEvent.md @@ -4,10 +4,10 @@ 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) ``` @@ -20,51 +20,42 @@ const onSomething = useEffectEvent(callback) ### `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 declare 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); }); - - useEffect(() => { - const connection = createConnection(serverUrl, roomId); - connection.on('connected', () => { - onConnected(); - }); - connection.connect(); - return () => connection.disconnect(); - }, [roomId]); - - // ... } ``` +Effect Events are functions you can call inside Effects, such as `useEffect`. + [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 values from props and state at the time of the call. This helps avoid issues with stale closures. +* `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 values from props and state 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. +`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 (version 6.1.1 or higher) enforces this restriction. -* Calling an Effect Event during rendering will throw an error: `"A function wrapped in useEffectEvent can't be called during rendering."` -* Do not include Effect Events in your Effect's dependency array. The function identity is intentionally non-stable, and including it would cause unnecessary Effect re-runs. The linter will warn if you try to do this. -* React does not preserve the `this` binding when you pass object methods to `useEffectEvent`. If you need to preserve `this`, bind the method first or use an arrow function wrapper. -* 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 genuinely should not re-trigger your Effect. +* 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 is the function identity intentionally non-stable? {/*why-non-stable-identity*/} +#### 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: @@ -75,13 +66,11 @@ useEffect(() => { }, [onSomething]); // ESLint will warn about this ``` -Never include an Effect Event in your dependency array. The linter will warn you if you try. +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. -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 could 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. -If the identity were stable, you might accidentally include an Effect Event in a dependency array without the linter catching it. 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 the rule that Effect Events are "escape hatches" for reading the latest values, not general-purpose callbacks to be passed around. +This design reinforces the rule that Effect Events are "escape hatches" for reading the latest values, not general purpose callbacks to be passed around. @@ -89,334 +78,336 @@ This design reinforces the rule that Effect Events are "escape hatches" for read ## Usage {/*usage*/} -### Reading the latest props and state {/*reading-the-latest-props-and-state*/} - -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. - -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. - -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. - - - -```js -import { useState, useEffect, useEffectEvent } from 'react'; - -function Page({ url }) { - const [items, setItems] = useState([ - { id: 1, name: 'Apples' }, - { id: 2, name: 'Oranges' } - ]); - const onNavigate = useEffectEvent((visitedUrl) => { - console.log('Visited:', visitedUrl, 'with', items.length, 'items in cart'); - }); - - useEffect(() => { - onNavigate(url); - }, [url]); - - return ( - <> -

Page: {url}

-

Items in cart: {items.length}

- - - ); -} +### Using an event in an Effect {/*using-an-event-in-an-effect*/} -export default function App() { - const [url, setUrl] = useState('/home'); +Call `useEffectEvent` at the top level of your component to create an *Effect Event*: - return ( - <> - -
- - - ); -} -``` -```css -nav button { margin-right: 8px; } +```js [[1, 1, "onConnected"]] +const onConnected = useEffectEvent(() => { + if (!muted) { + showNotification('Connected!'); + } +}); ``` - - -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 `items` changes. By wrapping the logging logic in an Effect Event, `items.length` becomes non-reactive. The Effect Event always reads the latest value without triggering the Effect. +`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: -Try clicking "Add item" and notice that no log appears. Then click a navigation button—the log appears and shows the current number of items. +```js [[1, 3, "onConnected"]] +useEffect(() => { + const connection = createConnection(roomId); + connection.on('connected', onConnected); + connection.connect(); + return () => { + connection.disconnect(); + } +}, [roomId]); +``` -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. +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. +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 onFetch = useEffectEvent(() => { - fetchData(userId); // userId should trigger refetch! +const logVisit = useEffectEvent(() => { + log(pageUrl); }); useEffect(() => { - onFetch(); -}, []); // Missing userId means stale data + 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—like showing a notification in the current theme while connecting to a server. +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. --- -### Connecting to a chat room {/*connecting-to-a-chat-room*/} - -This example shows the primary use case for `useEffectEvent`: connecting to an external system where you want to react to some changes but not others. +### Using a timer with latest values {/*using-a-timer-with-latest-values*/} -In this chat room example, the Effect connects to a chat server based on `roomId`. When the user changes the theme, you want to show a notification in the current theme color—but you don't want to reconnect to the server because the theme changed. +When you use `setInterval` or `setTimeout` in an Effect, you often want to read the latest state values without restarting the timer whenever those values change. - - -#### Reading latest theme without reconnecting {/*reading-latest-theme*/} - -Change the room and notice the console logs showing connection and disconnection. Then change the theme—the notification uses the current theme, but no reconnection happens. +This counter increments by the current `increment` value every second. The `onTick` Effect Event reads the latest `increment` without causing the interval to restart: ```js import { useState, useEffect, useEffectEvent } from 'react'; -function ChatRoom({ roomId, theme }) { - const onConnected = useEffectEvent(() => { - console.log('✅ Connected to ' + roomId + ' (theme: ' + theme + ')'); +export default function Timer() { + const [count, setCount] = useState(0); + const [increment, setIncrement] = useState(1); + + const onTick = useEffectEvent(() => { + setCount(c => c + increment); }); useEffect(() => { - console.log('⏳ Connecting to ' + roomId + '...'); - const id = setTimeout(() => { - onConnected(); + const id = setInterval(() => { + onTick(); }, 1000); return () => { - console.log('❌ Disconnected from ' + roomId); - clearTimeout(id); + clearInterval(id); }; - }, [roomId]); - - return

Welcome to the {roomId} room!

; -} - -export default function App() { - const [roomId, setRoomId] = useState('general'); - const [theme, setTheme] = useState('light'); + }, []); return ( <> - - +

+ Counter: {count} + +

- +

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

); } ``` ```css -label { display: block; margin-bottom: 8px; } +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. -#### With muted notifications {/*with-muted-notifications*/} +--- + +### Using an event listener with latest state {/*using-an-event-listener-with-latest-state*/} + +When you set up an event listener in an Effect, you often need to read the latest state in the callback. Without `useEffectEvent`, you would need to include the state in your dependencies, causing the listener to be removed and re-added on every change. -This example adds a `muted` state that controls whether the Effect Event shows notifications. The Effect Event reads the latest `muted` value without re-triggering the connection. +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'; -function ChatRoom({ roomId, theme, muted }) { - const onConnected = useEffectEvent(() => { - if (!muted) { - console.log('✅ Connected to ' + roomId + ' (theme: ' + theme + ')'); - } else { - console.log('✅ Connected to ' + roomId + ' (muted)'); +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(() => { - console.log('⏳ Connecting to ' + roomId + '...'); - const id = setTimeout(() => { - onConnected(); - }, 1000); - return () => { - console.log('❌ Disconnected from ' + roomId); - clearTimeout(id); - }; - }, [roomId]); - - return

Welcome to the {roomId} room!

; -} - -export default function App() { - const [roomId, setRoomId] = useState('general'); - const [theme, setTheme] = useState('light'); - const [muted, setMuted] = useState(false); + window.addEventListener('pointermove', onMove); + return () => window.removeEventListener('pointermove', onMove); + }, []); return ( <> - -
- +
); } ``` ```css -label { display: block; margin-bottom: 8px; } +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. --- -### Passing reactive values to Effect Events {/*passing-reactive-values-to-effect-events*/} +### 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. -You can pass arguments to your Effect Event function. This is useful when you have a reactive value that should trigger your Effect, but you also want to use that value inside the Effect Event along with other non-reactive values. +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 Analytics({ url, userId }) { - const [sessionDuration, setSessionDuration] = useState(0); - - useEffect(() => { - const id = setInterval(() => { - setSessionDuration(d => d + 1); - }, 1000); - return () => clearInterval(id); - }, []); - - const onPageView = useEffectEvent((visitedUrl) => { - // visitedUrl is passed as argument - reactive - // userId and sessionDuration are read from closure - non-reactive - console.log('Page view:', visitedUrl); - console.log(' User:', userId); - console.log(' Session duration:', sessionDuration, 'seconds'); +function ChatRoom({ roomId, muted }) { + const onConnected = useEffectEvent((roomId) => { + console.log('✅ Connected to ' + roomId + ' (muted: ' + muted + ')'); + if (!muted) { + showNotification('Connected to ' + roomId); + } }); useEffect(() => { - onPageView(url); - }, [url]); + const connection = createConnection(roomId); + console.log('⏳ Connecting to ' + roomId + '...'); + connection.on('connected', () => { + onConnected(roomId); + }); + connection.connect(); + return () => { + console.log('❌ Disconnected from ' + roomId); + connection.disconnect(); + } + }, [roomId]); - return ( -
-

Analytics for: {url}

-

User: {userId}

-

Session: {sessionDuration}s

-
- ); + return

Welcome to the {roomId} room!

; } export default function App() { - const [url, setUrl] = useState('/home'); - const [userId, setUserId] = useState('user-123'); - + const [roomId, setRoomId] = useState('general'); + const [muted, setMuted] = useState(false); return ( <> -
- - - -
-
- -
+ +
- + ); } ``` +```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); + } + }; +} +``` + +```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(); +} +``` + ```css -button { margin-right: 8px; margin-bottom: 8px; } +label { display: block; margin-top: 10px; } ``` -In this example: -- `url` is passed as an argument to `onPageView`. This keeps it reactive—when `url` changes, the Effect runs again and calls `onPageView` with the new URL. -- `userId` and `sessionDuration` are read from closure inside the Effect Event. They're non-reactive—changing them doesn't re-run the Effect, but `onPageView` always sees their latest values when called. - -Try clicking "Change user" or waiting for the session timer—no log appears. Then click a navigation button—the log shows the current user and session duration. +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. --- ### 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. +You can use `useEffectEvent` inside your own custom Hooks. This lets you create reusable Hooks that encapsulate Effects while keeping some values non-reactive: @@ -481,16 +472,7 @@ label { display: block; margin-bottom: 8px; } -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 is set up once when the component mounts (or when `delay` changes). -- Changing `incrementBy` doesn't restart the interval, but the callback always uses the latest value. - - - -Effect Events are designed to be called locally within the same component or Hook. Do not pass Effect Event functions to other components or Hooks—the linter will warn if you try. If you need to share event logic across components, consider lifting the Effect up or using a different pattern. - - +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. --- @@ -542,13 +524,13 @@ useEffect(() => { }, []); ``` -Effect Events are designed to be called from Effects without being listed as dependencies. The linter enforces this because the function identity is intentionally non-stable—including it would cause your Effect to re-run on every render. +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. --- -### I'm getting a lint error: "onSomething is a function created with useEffectEvent, and can only be called from Effects" {/*effect-event-called-outside-effect*/} +### 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 "`onSomething` 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: +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(() => { @@ -569,14 +551,4 @@ useEffect(() => { }, []); ``` -Effect Events are specifically designed to read the latest values inside Effects. If you need a callback for event handlers or to pass to children, use a regular function or `useCallback` instead. - ---- - -### I'm seeing stale values when using Effect Events with `memo()` {/*stale-values-with-memo*/} - -There was a known bug in React where `useEffectEvent` could see stale closure values when used inside components wrapped with `memo()` or `forwardRef()`. This bug affected some React 19 versions. - -**Status:** React fixed this bug in [PR #34831](https://github.com/facebook/react/pull/34831). - -**Solution:** Update to the latest React version. If you can't update immediately, you can work around this by removing `memo()` temporarily or by restructuring your component to avoid the problematic pattern. \ No newline at end of file +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