Solution

You'll create an IntersectionObserver in an effect, push its entry into state, and disconnect on cleanup — with a derived frozen flag that keys the effect off once the element has been seen.

The problem, in plain English

The old way to answer "is this visible?" was a scroll listener doing getBoundingClientRect math on every frame — expensive and janky. IntersectionObserver flips it around: you hand the browser an element and a threshold, and it asynchronously calls you only when the element's visibility actually crosses that line. The hook's job is lifecycle plumbing: construct the observer when there's an element, route its callback into React state, and tear it down when the element changes or the component unmounts. The one feature with real logic is freezeOnceVisible — stop watching after the first appearance.

The mental model

An effect owns one observer. When the effect runs, it builds an IntersectionObserver whose callback does setEntry(entry); it observes the node and returns a cleanup that disconnects. That single setEntry is the bridge from the browser's async notification to a React re-render. freezeOnceVisible becomes a derived boolean — "have we already seen it and do we want to freeze?" — that's in the effect's dependency array, so when it flips true, React runs the cleanup (disconnecting) and the effect early-returns without re-observing. The last entry stays frozen in state.

A first attempt

The tempting version observes without cleanup or guards:

function useIntersectionObserverNaive(ref, options) {
  const [entry, setEntry] = useState();
  useEffect(() => {
    const observer = new IntersectionObserver(([e]) => setEntry(e), options);
    observer.observe(ref.current); // throws if ref.current is null
    // no cleanup -> observer leaks, keeps firing after unmount
  }, [options]); // new options object each render -> re-subscribes constantly
}

Three problems. If ref.current is null (first render, conditional element), observe(null) throws. With no cleanup, each re-run leaks an observer that keeps calling setEntry after unmount. And depending on the options object — freshly built every render — re-subscribes on every render. The fix is to guard the node, disconnect in cleanup, and depend on the primitive option values.

The working solution

const { useState, useEffect } = require('react');

function useIntersectionObserver(
  elementRef,
  { threshold = 0, root = null, rootMargin = '0%', freezeOnceVisible = false } = {},
) {
  const [entry, setEntry] = useState();

  // Freeze after the element has been seen (one-shot reveal / lazy-load).
  const frozen = Boolean(entry?.isIntersecting) && freezeOnceVisible;

  useEffect(() => {
    const node = elementRef?.current;
    const hasSupport = typeof IntersectionObserver !== 'undefined';
    if (!hasSupport || !node || frozen) return; // nothing to (re)observe

    const observer = new IntersectionObserver(([e]) => setEntry(e), {
      threshold,
      root,
      rootMargin,
    });
    observer.observe(node);

    return () => observer.disconnect();
  }, [elementRef, threshold, root, rootMargin, frozen]);

  return entry;
}

module.exports = { useIntersectionObserver };

The effect first guards: no observer if there's no support, no element, or we've frozen — so observe never sees null. Otherwise it constructs the observer with the primitive options (threshold/root/rootMargin), observes the node, and returns a disconnect cleanup that runs on unmount and whenever a dependency changes. The dependency array is the primitive option values plus frozen (not the options object), so it re-subscribes only when something meaningful changes. frozen is derived: true only when the element has intersected and freezeOnceVisible is set; when it flips true, React disconnects (cleanup) and the effect early-returns, leaving the last entry in state permanently.

Walking through one call

useIntersectionObserver(ref, { freezeOnceVisible: true }) on a lazy-loaded image:

• mount — entry is undefined, so frozen is false. The effect runs: builds an observer, observe(ref.current). The hook returns undefined → the component shows a placeholder.
• element scrolls into view — the browser calls the observer's callback with entry.isIntersecting === true; setEntry(entry) re-renders. Now entry?.isIntersecting is true and freezeOnceVisible is true, so frozen becomes true.
• frozen flips true — frozen changed, so React runs the effect's cleanup (observer.disconnect()), then re-runs the effect body, which hits if (… || frozen) return and creates no new observer.
• result — the image loads and stays loaded; the observer is gone, doing zero work for the rest of the page's life.

Gotchas

• observe(null) — throws when the element isn't mounted yet. Guard on ref.current before observing.
• No disconnect — leaks an observer that fires after unmount. Return observer.disconnect from the effect.
• Depending on the options object — a new object each render re-subscribes constantly. Depend on the primitive fields.
• No feature/SSR guard — IntersectionObserver is undefined on the server and in old browsers; check typeof before constructing.

Going further

• useInView sugar — returning just [ref, isIntersecting] with an internally-created ref (a callback ref) is the ergonomic form popular libraries expose.
• Lazy-loading & infinite scroll — a zero-height sentinel at the list's end plus this hook triggers "load more" exactly when the user reaches the bottom.
• Multiple thresholds — passing threshold: [0, 0.25, 0.5, 1] gives graduated intersectionRatio callbacks, enough to drive scroll-linked animations.