|
| 1 | +--- |
| 2 | +title: useEffectEvent |
| 3 | +version: canary |
| 4 | +--- |
| 5 | + |
| 6 | + |
| 7 | +<Canary> |
| 8 | + |
| 9 | +**The `useEffectEvent` API is currently only available in React’s Canary and Experimental channels.** |
| 10 | + |
| 11 | +[Learn more about React’s release channels here.](/community/versioning-policy#all-release-channels) |
| 12 | + |
| 13 | +</Canary> |
| 14 | + |
| 15 | +<Intro> |
| 16 | + |
| 17 | +`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). |
| 18 | + |
| 19 | +```js |
| 20 | +const onSomething = useEffectEvent(callback) |
| 21 | +``` |
| 22 | + |
| 23 | +</Intro> |
| 24 | + |
| 25 | +<InlineToc /> |
| 26 | + |
| 27 | +## Reference {/*reference*/} |
| 28 | + |
| 29 | +### `useEffectEvent(callback)` {/*useeffectevent*/} |
| 30 | + |
| 31 | +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`: |
| 32 | + |
| 33 | +```js {4-6,11} |
| 34 | +import { useEffectEvent, useEffect } from 'react'; |
| 35 | + |
| 36 | +function ChatRoom({ roomId, theme }) { |
| 37 | + const onConnected = useEffectEvent(() => { |
| 38 | + showNotification('Connected!', theme); |
| 39 | + }); |
| 40 | + |
| 41 | + useEffect(() => { |
| 42 | + const connection = createConnection(serverUrl, roomId); |
| 43 | + connection.on('connected', () => { |
| 44 | + onConnected(); |
| 45 | + }); |
| 46 | + connection.connect(); |
| 47 | + return () => connection.disconnect(); |
| 48 | + }, [roomId]); |
| 49 | + |
| 50 | + // ... |
| 51 | +} |
| 52 | +``` |
| 53 | + |
| 54 | +[See more examples below.](#usage) |
| 55 | + |
| 56 | +#### Parameters {/*parameters*/} |
| 57 | + |
| 58 | +- `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. |
| 59 | + |
| 60 | +#### Returns {/*returns*/} |
| 61 | + |
| 62 | +Returns an Effect Event function. You can call this function inside `useEffect`, `useLayoutEffect`, or `useInsertionEffect`. |
| 63 | + |
| 64 | +#### Caveats {/*caveats*/} |
| 65 | + |
| 66 | +- **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. |
| 67 | +- **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. |
| 68 | +- **Use for non-reactive logic:** Only use `useEffectEvent` to extract logic that does not depend on changing values. |
| 69 | + |
| 70 | +___ |
| 71 | + |
| 72 | +## Usage {/*usage*/} |
| 73 | + |
| 74 | +### Reading the latest props and state {/*reading-the-latest-props-and-state*/} |
| 75 | + |
| 76 | +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. |
| 77 | + |
| 78 | +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. |
| 79 | + |
| 80 | +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. |
| 81 | + |
| 82 | +```js {7-9,12} |
| 83 | +import { useEffect, useContext, useEffectEvent } from 'react'; |
| 84 | + |
| 85 | +function Page({ url }) { |
| 86 | + const { items } = useContext(ShoppingCartContext); |
| 87 | + const numberOfItems = items.length; |
| 88 | + |
| 89 | + const onNavigate = useEffectEvent((visitedUrl) => { |
| 90 | + logVisit(visitedUrl, numberOfItems); |
| 91 | + }); |
| 92 | + |
| 93 | + useEffect(() => { |
| 94 | + onNavigate(url); |
| 95 | + }, [url]); |
| 96 | + |
| 97 | + // ... |
| 98 | +} |
| 99 | +``` |
| 100 | + |
| 101 | +You can pass reactive values like `url` as arguments to the Effect Event. This lets you access the latest values without making your Effect re-run for every change. |
| 102 | + |
0 commit comments