React useEffectEvent: A New Dimension for Reusable Hooks

Creating reusable hooks in React is a powerful tool, but it often leads to subtle problems with useEffect dependencies. Developers constantly reach for useRef to work around ever-changing functions and avoid unnecessary re-renders. React 19.2 has introduced useEffectEvent to solve this problem in a more elegant and declarative way.

✅ Available in React 19.2+ — useEffectEvent is now officially available in React. This article demonstrates how to use this new Hook to simplify your Effects. Official documentation

Note on Implementation Status: While the official React documentation lists useEffectEvent as available in React 19.2, the React source code still marks it with a $FlowFixMe[not-a-function] This is unstable, thus optional comment. This suggests the API may still be stabilizing internally. The Hook is exported and functional, but be aware that edge cases or implementation details might evolve in future React versions. Always check the official documentation for the most current status.

The Problem: Dependencies and the Closure Trap

In the standard approach, every external function or value used inside useEffect must be included in its dependency array. This mechanism guarantees that useEffect always operates on fresh data from the latest render.

The problem arises when one of the dependencies is a function (e.g., the onOutsideClick callback), which is often recreated on every render of the parent component.

Let's see this problem in action with a concrete example:

function SearchBar({ onSearch }: { onSearch: (query: string) => void }) {
  const [query, setQuery] = useState('');

  // ❌ Problem 1: Adding function to dependencies causes excessive re-runs
  useEffect(() => {
    console.log('Effect running!');
    const debounced = setTimeout(() => {
      onSearch(query);
    }, 500);

    return () => clearTimeout(debounced);
  }, [query, onSearch]); // onSearch changes every render!

  return <input value={query} onChange={(e) => setQuery(e.target.value)} />;
}

// Parent component
function App() {
  const [results, setResults] = useState([]);

  // This function is recreated on EVERY render
  const handleSearch = (query: string) => {
    fetch(`/api/search?q=${query}`)
      .then(res => res.json())
      .then(setResults);
  };

  return <SearchBar onSearch={handleSearch} />;
  // Every time App renders (e.g., results change), handleSearch is new
  // This causes SearchBar's effect to re-run, which re-fetches, which updates results
  // Which causes another render... potentially infinite loop!
}

// ❌ Problem 2: Omitting function from dependencies causes stale closures
function Counter() {
  const [count, setCount] = useState(0);

  const logCount = () => {
    console.log(`Current count: ${count}`);
  };

  useEffect(() => {
    const interval = setInterval(() => {
      logCount(); // Calls the function
    }, 1000);

    return () => clearInterval(interval);
  }, []); // logCount is NOT in dependencies

  return (
    <div>
      <p>Count: {count}</p>
      <button onClick={() => setCount(count + 1)}>Increment</button>
    </div>
  );
  // The interval will ALWAYS log "Current count: 0"
  // even as count increases, because logCount is "frozen" from the first render
}

The Dependency Dilemma

You're caught between two bad options:

Real-World Impact: In 2025, Cloudflare experienced service degradation when a React useEffect dependency issue in their internal dashboard caused cascading re-renders, effectively DDoSing their own systems during incident response. This isn't just about performance—it's about system stability.

The "Old Way" with useRef: The Latest Ref Pattern

To work around this, a popular pattern was to store the latest version of the function in a reference (useRef). A ref is a mutable object that "survives" re-renders, which allows you to omit the function itself from the useEffect dependency array. This technique is commonly known as the "Latest Ref Pattern" or "Stable Callback Ref Pattern" in the React community.

This pattern is widely used in production codebases. For example, libraries like react-use, usehooks-ts, and countless internal implementations use this exact approach.

Real-World Example from usehooks-ts

One of the most popular implementations is the useEventListener hook from usehooks-ts, a library with over 1 million weekly downloads on npm:

function useEventListener<K extends keyof WindowEventMap>(
  eventName: K,
  handler: (event: WindowEventMap[K]) => void,
  element?: RefObject<HTMLElement>,
  options?: boolean | AddEventListenerOptions,
) {
  // Create a ref that stores handler
  const savedHandler = useRef(handler);

  // Update ref.current value if handler changes.
  // This allows our effect below to always get latest handler
  // without needing to pass it in effect deps array
  useIsomorphicLayoutEffect(() => {
    savedHandler.current = handler;
  }, [handler]);

  useEffect(() => {
    // Define the listening target
    const targetElement: HTMLElement | Window = element?.current ?? window;

    if (!(targetElement && targetElement.addEventListener)) return;

    // Create event listener that calls handler function stored in ref
    const listener = (event: Event) => {
      savedHandler.current(event);
    };

    targetElement.addEventListener(eventName, listener, options);

    // Remove event listener on cleanup
    return () => {
      targetElement.removeEventListener(eventName, listener, options);
    };
  }, [eventName, element, options]); // handler is NOT in deps!
}

Key observations:

• Uses useRef to store the handler: const savedHandler = useRef(handler)
• Uses useIsomorphicLayoutEffect to keep the ref updated - this is crucial for timing
• The main Effect omits handler from dependencies but uses savedHandler.current
• This ensures the event listener is set up once per eventName/element/options change, but always calls the latest handler

Why useIsomorphicLayoutEffect?

// SSR-compatible: uses useLayoutEffect on client, useEffect on server
const useIsomorphicLayoutEffect =
  typeof window !== 'undefined' ? useLayoutEffect : useEffect;

Why useLayoutEffect for ref updates?

Note: Many implementations use useEffect for both and work fine. useLayoutEffect is technically more correct but the practical difference is minimal.

This is the Latest Ref Pattern in action in a production library trusted by thousands of projects.

Another Example from Internal Codebase

Here's another real-world example from a production codebase showing the useAppEvent hook that subscribes to application events:

const useAppEvent = (callback: (event: AppEvent) => void): void => {
  const callbackRef = useRef(callback);

  useLayoutEffect(() => {
    callbackRef.current = callback;
  }, [callback]);

  useEffect(() => {
    const subscription = subscribe(callbackRef.current);
    return () => {
      subscription.unsubscribe();
    };
  }, []); // Empty deps - subscription persists, but callback stays fresh
};

This pattern separates the subscription lifecycle (which should run once) from the callback updates (which happen on every render).

Now let's look at a more complex example with the useOnOutsideClick hook. This implementation takes a slightly different approach by creating and returning the ref internally, rather than accepting it as a parameter. This design choice offers several benefits:

1. Simpler API: Consumers don't need to manage refs themselves
2. Encapsulation: The hook owns the lifecycle of both the ref and the event listener
3. Type safety: The generic type parameter ensures the returned ref matches the element type
4. Common pattern: Many popular hooks (like react-use's useMeasure, useClickAway) follow this pattern

const useOnOutsideClick = <T extends HTMLElement = HTMLElement>(
  handler?: (event: MouseEvent) => void,
  enabled: boolean = true,
): RefObject<T | null> => {
  // Create ref internally
  const ref = useRef<T>(null);
  
  // Store handler in ref
  const savedHandler = useRef(handler);

  // Update ref when handler changes (synchronously before effects run)
  useLayoutEffect(() => {
    savedHandler.current = handler;
  }, [handler]);

  useEffect(() => {
    // Don't set up listener if disabled
    if (!enabled) return;

    const element = ref.current;
    if (!element) return;

    const handleClickOutside = (event: MouseEvent) => {
      // Call the latest handler via ref
      if (!element.contains(event.target as Node)) {
        savedHandler.current?.(event);
      }
    };

    document.addEventListener("mousedown", handleClickOutside);
    return () => {
      document.removeEventListener("mousedown", handleClickOutside);
    };
  }, [enabled]); // handler is NOT in dependencies

  return ref; // Return the ref for the consumer to attach
};

This solution works, but it's not very intuitive and requires:

• Two separate refs (ref for the element, savedHandler for the callback)
• An extra useLayoutEffect just to update the handler reference
• Understanding of Effect timing to avoid race conditions

All of this obscures the code's intent and adds cognitive overhead.

Why This Pattern Matters: The Consumer's Perspective

The Latest Ref Pattern removes the burden from the consumer (parent component) to memoize their callbacks. Without this pattern, the parent would need to wrap every callback in useCallback:

// Without Latest Ref Pattern - consumer must use useCallback
function Dropdown() {
  const ref = useRef<HTMLDivElement>(null);
  const [count, setCount] = useState(0);

  // REQUIRED: Must wrap in useCallback to prevent re-subscriptions
  const handleOutsideClick = useCallback(() => {
    console.log('Clicked outside!', count); // ❌ 'count' would be stale without [count]
  }, [count]); // ⚠️ Adding 'count' causes re-subscription on every count change

  useOnOutsideClickWithoutPattern(ref, handleOutsideClick); // Re-subscribes frequently
  
  return <div ref={ref}>Count: {count}</div>;
}

// With Latest Ref Pattern - no useCallback needed!
function Dropdown() {
  const [count, setCount] = useState(0);

  // ✅ Hook creates and returns the ref - just pass the inline function
  const ref = useOnOutsideClick<HTMLDivElement>(
    () => {
      console.log('Clicked outside!', count); // ✅ Always has latest count
    },
    true, // enabled
  ); // Subscribes once, callback stays fresh
  
  return <div ref={ref}>Count: {count}</div>;
}

The key benefit: The hook consumer can pass inline functions without worrying about performance or stale closures. The Latest Ref Pattern handles the complexity internally. Additionally, returning the ref from the hook creates a cleaner API - consumers don't need to create and manage their own refs.

The New Approach: useEffectEvent

The useEffectEvent hook was designed to formally separate logic that should not be reactive from the effect itself, which is reactive. A function wrapped in useEffectEvent (called an "Effect Event") will always have access to the latest props and state, but it will never trigger a re-run of useEffect.

Important Rules and Caveats

According to the official React documentation, there are critical rules to follow:

1. Only call inside Effects: Effect Events should only be called within useEffect, useLayoutEffect, or useInsertionEffect. Do not pass them to other components or hooks. The eslint-plugin-react-hooks linter (version 6.1.1+) enforces this restriction.

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

3. Use for non-reactive logic only: Only use useEffectEvent to extract logic that should read the latest values without causing the Effect to re-synchronize.

Community Solutions Before useEffectEvent

Before React 19.2, developers used three main patterns. Here's a quick comparison:

Pattern 1: Latest Ref + Manual Sync

const callbackRef = useRef(callback);
useLayoutEffect(() => { callbackRef.current = callback; }, [callback]);
useEffect(() => { /* use callbackRef.current */ }, []);

Pattern 2: Ref + useCallback Hybrid

const callbackRef = useRef(callback);
callbackRef.current = callback; // During render!
const stable = useCallback((...args) => callbackRef.current?.(...args), []);

Pattern 3: Custom useEvent Hook

function useEvent<T extends (...args: any[]) => any>(callback: T): T {
  const ref = useRef<T>(callback);
  useLayoutEffect(() => { ref.current = callback; }, [callback]);
  return useCallback((...args: any[]) => ref.current(...args), []) as T;
}

Why useEffectEvent is Better

✅ First-class API with clear semantics
✅ Linter-aware (ESLint v6.1.1+ enforces proper usage)
✅ Effect-only restriction prevents misuse
✅ Internally optimized by React
✅ Consistent across all codebases

Refactoring useOnOutsideClick

Let's see how useEffectEvent simplifies our hook:

const useOnOutsideClick = <T extends HTMLElement = HTMLElement>(
  handler?: (event: MouseEvent) => void,
  enabled: boolean = true,
): RefObject<T | null> => {
  // Create ref internally
  const ref = useRef<T>(null);
  
  // `onEvent` doesn't need to be in deps but always calls the latest handler
  const onEvent = useEffectEvent((event: MouseEvent) => {
    const element = ref.current;
    if (element && !element.contains(event.target as Node)) {
      handler?.(event);
    }
  });

  useEffect(() => {
    if (!enabled) return; 

    document.addEventListener("mousedown", onEvent);
    return () => {
      document.removeEventListener("mousedown", onEvent);
    };
  }, [enabled]); 
  
  return ref; // Return ref for consumer to attach
};

Important: The function returned by useEffectEvent does NOT need to be included in the useEffect dependency array. React internally manages keeping the callback fresh without requiring it as a dependency. ESLint's exhaustive-deps rule (v6.1.1+) understands this and will not warn you about omitting Effect Events from dependencies. This is a key difference from regular functions—Effect Events are designed specifically so that changes to the callback don't cause Effects to re-run, while still always calling the latest version.

Comparison: Latest Ref Pattern vs useEffectEvent

// Latest Ref Pattern - requires TWO refs and useLayoutEffect
const ref = useRef<T>(null);           // For the element
const savedHandler = useRef(handler);   // For the callback
useLayoutEffect(() => {
  savedHandler.current = handler;
}, [handler]);

// useEffectEvent - only ONE ref, no sync effect needed
const ref = useRef<T>(null);           // For the element only
const onEvent = useEffectEvent(() => { /* ... */ }); // Callback handled automatically

The code is significantly cleaner and more readable:

• Eliminated: The handler ref (savedHandler) and the extra useLayoutEffect
• Simplified: Only one ref needed (for the element), callback freshness handled by React
• Clearer intent: The outside click logic has been extracted into onEvent, and useEffect now only handles what is truly reactive: adding and removing the listener

Real-World Example: Chat Room with Notifications

Here's a practical example inspired by the official React documentation that demonstrates the power of useEffectEvent:

import { useEffect, useEffectEvent } from "react";

function ChatRoom({ roomId, theme }: { roomId: string; theme: string }) {
  // `theme` can change frequently, but we don't want to reconnect the chat
  const onConnected = useEffectEvent(() => {
    showNotification('Connected!', theme); // Always uses the latest theme
  });

  useEffect(() => {
    const connection = createConnection(serverUrl, roomId);
    
    connection.on('connected', () => {
      onConnected(); // Calls the latest version with current theme
    });
    
    connection.connect();
    
    return () => connection.disconnect();
  }, [roomId]); // Only reconnect when roomId changes, not theme

  return <div className={theme}>Chat Room: {roomId}</div>;
}

In this example:

• The Effect reconnects only when roomId changes (reactive dependency)
• The notification always uses the latest theme value (non-reactive, accessed via Effect Event)
• Without useEffectEvent, you'd either have stale theme values or unnecessary reconnections

Distinguishing Reactive vs Non-Reactive Dependencies

The key question: "If this value changes, should my Effect clean up and restart?"

Quick Examples

// roomId changes = must reconnect
useEffect(() => {
  const conn = createConnection(roomId);
  conn.connect();
  return () => conn.disconnect();
}, [roomId]);

// url changes = must re-fetch
useEffect(() => {
  fetch(url).then(/* ... */);
}, [url]);

// isEnabled changes = add/remove subscription
useEffect(() => {
  if (!isEnabled) return;
  const sub = api.subscribe(/* ... */);
  return () => sub.unsubscribe();
}, [isEnabled]);

// theme changes = don't reconnect, just use latest when notifying
const onConnected = useEffectEvent(() => {
  showNotification('Connected!', theme);
});
useEffect(() => {
  const conn = createConnection(roomId);
  conn.on('connected', onConnected);
  conn.connect();
  return () => conn.disconnect();
}, [roomId]); // theme NOT here

// userId changes = don't re-track, just use latest in log
const onVisit = useEffectEvent(() => {
  analytics.log('page_view', { userId });
});
useEffect(() => { onVisit(); }, []);

// callback changes = don't re-fetch, just use latest
const handleSuccess = useEffectEvent((data) => onSuccess(data));
useEffect(() => {
  fetch(url).then(handleSuccess);
}, [url]); // onSuccess NOT here

Quick Decision Tree

Is the value used in the Effect?
  │
  ├─ No → Don't include it anywhere
  │
  └─ Yes → Does changing this value require:
            - Reconnecting something?
            - Re-fetching data?
            - Adding/removing listeners differently?
            - Restarting a timer or subscription?
            │
            ├─ Yes → REACTIVE: Put in dependency array
            │
            └─ No → Is it only used to:
                     - Log/track with latest info?
                     - Show notifications with current data?
                     - Call a callback during an event?
                     │
                     └─ Yes → NON-REACTIVE: Use useEffectEvent

Common Mistakes

// ❌ BAD: productId SHOULD trigger re-fetch
const fetchData = useEffectEvent(() => fetch(`/api/${productId}`));
useEffect(() => { fetchData(); }, []); // BUG: won't re-run when productId changes

// ✅ GOOD: productId is reactive
useEffect(() => { fetch(`/api/${productId}`); }, [productId]);

// ❌ BAD: Reconnects every time onMessage changes
useEffect(() => {
  connection.on('message', onMessage);
  connection.connect();
  return () => connection.disconnect();
}, [onMessage]); // Unnecessary reconnections

// ✅ GOOD: Connection reactive, handler not
const handleMessage = useEffectEvent((msg) => onMessage(msg));
useEffect(() => {
  connection.on('message', handleMessage);
  connection.connect();
  return () => connection.disconnect();
}, []); // Connection persists, handler stays fresh

Two Directions for Hooks in React

The introduction of useEffectEvent highlights an interesting direction for React's API: a formal distinction between two types of logic in components.

1. Reactive Logic (Closure-dependent): This is the standard behavior of useEffect. The effect is tightly coupled with the values from a specific render and must be re-run when those values change. A perfect example is data fetching:

   useEffect(() => {
     fetchData(productId);
   }, [productId]); // We want to fetch new data when `productId` changes.
   

2. Non-reactive ("Event-like") Logic: This is the job for useEffectEvent. It defines an event that can be called from within an effect. We want it to always have access to the latest data, but a change in the event's logic itself should not reset the effect. An example is analytics tracking:

   const onLog = useEffectEvent((details) => {
     logAnalytics('visit', { ...details, userId }); // `userId` is always up-to-date
   });
   
   useEffect(() => {
     // ...logic for tracking a page visit
     onLog({ page: 'HomePage' });
   }, []); // Runs only once, but `onLog` is never "stale".
   

How Does It Work?

Under the hood, useEffectEvent is essentially a formalized version of the useRef pattern, but built into React's core:

1. Doesn't Trigger Re-runs: The returned function doesn't need to be in dependency arrays - React handles this specially
2. Automatic Updates: React automatically maintains an internal ref that always points to your latest callback
3. No Manual Deps: You never need to add Effect Events to dependency arrays (ESLint knows this)
4. Latest Values: When called, it always executes the most recent version with current props and state

This makes the pattern explicit and removes the boilerplate of manually managing refs and sync Effects. The React team can also optimize this internally and provide better debugging tools.

Key Insight: useEffectEvent gives you the best of both worlds - the function behaves as if it's not in the dependencies (Effect doesn't re-run when callback changes), but when it executes, it sees the latest values. React manages this internally using a pattern similar to the Latest Ref Pattern we saw earlier.

Comparison:

// Manual pattern (old way) - requires explicit ref management
const callbackRef = useRef(callback);
useLayoutEffect(() => {
  callbackRef.current = callback;
}, [callback]);

// Built-in (new way) - React handles everything automatically
const callback = useEffectEvent(() => { /* ... */ });
// React internally manages the ref and timing

When to Use (and When NOT to Use)

useEffectEvent is powerful for specific use cases, but it's not a universal solution. Here's when to use it:

✅ DO Use When:

• You need to read the latest props/state inside an Effect without making them reactive
• You're logging, tracking analytics, or showing notifications based on Effect events
• You have event handlers inside Effects that shouldn't cause re-synchronization
• You're currently using the useRef workaround to avoid stale closures

❌ DON'T Use When:

• The value should actually trigger the Effect to re-run:

  // ❌ BAD: Hiding a legitimate dependency
  const fetchProduct = useEffectEvent(() => {
    fetch(`/api/product/${productId}`); // productId SHOULD be reactive!
  });
  
  useEffect(() => {
    fetchProduct();
  }, []); // Effect won't re-run when productId changes - BUG!
  
  // ✅ GOOD: productId is a legitimate dependency
  useEffect(() => {
    fetch(`/api/product/${productId}`);
  }, [productId]); // Re-fetch when productId changes
  

• You want to pass the function to other components or hooks — Effect Events can only be called from within Effects

• You're trying to work around ESLint warnings — If ESLint suggests adding a dependency, there's usually a good reason

The Future: From Complexity to Simplicity

A Broader Trend in Frontend Frameworks

The evolution of React and the introduction of new APIs like useEffectEvent are part of a broader trend in the world of front-end frameworks. As powerful libraries mature, they inevitably become more complex, which can raise the barrier to entry for new developers.

Angular's Journey

Angular faced a similar challenge with its advanced change detection system based on Zone.js. While powerful, it felt "magical" and difficult to debug for many developers. Performance at scale was also a concern. The introduction of Signals was a conscious step toward simplifying the reactivity model, making it more explicit, predictable, and performant.

React's Path Forward

React is at an analogous point. The rules of hooks, particularly the need to manually manage dependency arrays in useEffect, useCallback, and useMemo, are one of the biggest challenges in learning React. It requires a deep understanding of closures and the rendering lifecycle.

The answer to this complexity is the React Compiler. This compiler, which has already reached a stable 1.0 version, aims to automate dependency management and memoization. Instead of forcing the developer to decide what to put in a dependency array, the compiler analyzes the code and optimizes it automatically.

What the React Compiler automates:

• ✅ Dependency array management for useEffect
• ✅ useCallback / useMemo optimization
• ✅ Effect optimization and memoization
• ✅ Eliminating unnecessary re-renders

The Vision for React v20-21

The vision for the future is that thanks to the compiler, the library's API could be significantly simplified:

• Perhaps the need to use useCallback or useMemo in application code will disappear entirely
• useEffect will become far more intuitive with automatic dependency tracking
• useEffectEvent will handle non-reactive logic explicitly
• Developers can focus on business logic rather than micro-optimizations

This is a direction that will lower the barrier to entry and allow developers to focus on what matters: building great user experiences, not wrestling with framework internals.

Migration Guide

Quick Start

# 1. Upgrade
npm install react@^19.2 react-dom@^19.2 eslint-plugin-react-hooks@^6.1.1

# 2. Find patterns to migrate
# Look for: useRef storing callbacks + sync useEffect or useLayoutEffect

Refactor Pattern

// Before: Two steps
const handlerRef = useRef(handler);
useEffect(() => { handlerRef.current = handler; }, [handler]);
useEffect(() => { /* use handlerRef.current */ }, [deps]);

// After: Direct use
const onHandler = useEffectEvent(handler);
useEffect(() => { /* use onHandler directly */ }, [deps]);

Migration Checklist

• ✅ Effects run at correct times
• ✅ Latest values captured
• ✅ ESLint happy with deps
• ✅ Team understands the pattern

When NOT to Migrate

⚠️ Skip migration if:

• Current code works and is clear to your team
• Not yet on React 19.2+
• No clear benefit from refactoring

Remember: Migrate to solve problems, not to chase new APIs.

Summary

useEffectEvent is a powerful tool, now officially available in React 19.2, that solves a fundamental problem in creating reusable hooks. It allows us to write cleaner, more predictable code by eliminating the need for useRef workarounds. More importantly, it introduces a clear distinction between reactive logic and events.

Key Takeaways:

• Now Stable: useEffectEvent is available in React 19.2+ and ready for production use
• Use Case: Perfect for reading latest props/state in Effects without making them reactive (logging, analytics, notifications)
• Not a Shortcut: Don't use it to hide legitimate dependencies—if a value should trigger re-synchronization, include it in the dependency array
• Effect-Only: Effect Events can only be called from within Effects (useEffect, useLayoutEffect, useInsertionEffect)
• Linter Support: ESLint plugin (v6.1.1+) enforces proper usage patterns

Looking at the bigger picture, this is a step towards a simpler and more accessible React. Combined with tools like the React Compiler, which automates dependency management and memoization, React is moving towards a future where developers can focus on business logic rather than micro-optimizations. The introduction of useEffectEvent demonstrates React's commitment to providing elegant solutions to common patterns, making the framework more intuitive for both new and experienced developers.

Learn More:

• Official React Documentation
• React 19 Release Notes