use-stable-reference

Simple React hooks to access referentially stable, up-to-date versions of non-primitives.

Basic usage

import { useStableCallback, useStableValue } from "use-stable-reference";

function Library({ unstableCallback, unstableValue }) {
  const stableCallback = useStableCallback(unstableCallback);
  const getStableValue = useStableValue(unstableValue);

  useEffect(() => {
    if (/* ... */) {
      stableCallback()
      const stableValue = getStableValue()
    }

    // safe to add to dependency arrays!
  }, [stableCallback, getStableValue, /* ... */]);
}

use-stable-reference really shines for library authors or for those writing reusable code. With a library-consumer relationship, the library author can't reasonably expect that the consumer will preemptively wrap any callbacks in a useCallback, or any referentially unstable values in a useMemo. This leaves the author with a few possible choices for how to handle consumer-provided non-primitive arguments:

1. Leave them out of any dependency arrays, and ignore any eslint React linter warnings/errors
2. Leave them in the dependency arrays, expecting that the effects / memoizations will run every render
3. Wrap them in a useStableCallback/useStableValue

With option 3, the returned callback/value-getter are referentially stable, can safely be used in dependency arrays, and are guaranteed to always be up-to-date if the underlying option ever changes! 🎉

useStableCallback

useStableCallback accepts one argument, a callback of type: (...args: any[]) => any

useStableCallback returns an up-to-date, referentially stable callback.

useStableValue

useStableValue accepts one argument, a value of type: unknown

useStableValue returns a referentially stable callback that returns an up-to-date copy of the argument.

Technical Notes

A version of this hook has been floating around the React community for a while, often referred to as useEvent or useEffectCallback. This package hopes to distill the best aspects of several different implementations:

• useEvent RFC, legacy React docs
  • Basic implementation
• wouter
  • Initializing the useRef to the callback argument, rather than null
• react-use-event-hook
  • Support passing a callback argument that uses the this keyword
• react-use/useLatest
  • Updating the ref in the render method
  • This method is controversial, but I think the trade-offs are worth it to ensure the returned stable callback is always up-to-date