useEffectEvent

const onEvent = useEffectEvent(callback)

• Reference
  • useEffectEvent(callback)
• Usage
  • Using an event in an Effect
  • Using a timer with latest values
  • Using an event listener with latest values
  • Avoid reconnecting to external systems
  • Using Effect Events in custom Hooks
• Troubleshooting
  • I’m getting an error: “A function wrapped in useEffectEvent can’t be called during rendering”
  • I’m getting a lint error: “Functions returned from useEffectEvent must not be included in the dependency array”
  • I’m getting a lint error: ”… is a function created with useEffectEvent, and can only be called from Effects”

Reference

useEffectEvent(callback)

Call useEffectEvent at the top level of your component to create an Effect Event.

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 to learn more.

See more examples below.

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

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

• 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 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.

// 🔴 Wrong: including Effect Event in dependencies
useEffect(() => {
  onSomething();
}, [onSomething]); // ESLint will warn about this

Usage

Using an event in an Effect

Call useEffectEvent at the top level of your component to create an Effect Event:

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:

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.

// 🔴 Wrong: Using Effect Events to hide dependencies
const logVisit = useEffectEvent(() => {
  log(pageUrl);
});

useEffect(() => {
  logVisit()
}, []); // Missing pageUrl means you miss logs