Observer v2

Use trackVisibility only when intersection alone is not enough and you accept narrower browser support.

Most applications should stick with the standard inView signal. Intersection Observer v2 adds trackVisibility and entry.isVisible for viewability cases where an intersecting element may be covered by something else or hidden behind a filter.

Enable visibility tracking

Set trackVisibility: true and a delay of at least 100 milliseconds:

import { useOnInView } from "react-intersection-observer";

declare global {
  interface IntersectionObserverEntry {
    isVisible?: boolean;
  }
}

export function Viewability({ onSeen }: { onSeen: () => void }) {
  const ref = useOnInView(
    (inView, entry) => {
      if (inView && entry.isVisible === true) onSeen();
    },
    {
      trackVisibility: true,
      delay: 100,
      threshold: 0.5,
      triggerOnce: true,
    },
  );

  return <div ref={ref}>Measured content</div>;
}

isVisible is not in TypeScript’s IntersectionObserverEntry declaration yet, so add the augmentation once in your application types before reading it. The option works with all three APIs. With useOnInView, read entry.isVisible inside the callback. With <InView>, read it from the render-prop entry or from onChange.

Support and fallback behavior

Fewer browsers support v2 than the original API. When a browser has Intersection Observer but no isVisible, this package falls back to v1 and sets entry.isVisible to the calculated intersection state. Treat that value as an approximation there.

Missing isVisible and a missing observer are separate problems. If the whole IntersectionObserver API is unavailable, use fallbackInView or defaultFallbackInView as described in Configuration.

Test it deliberately

Verify geometry, clipping, and real occlusion in a real browser. The package mock can drive the v1 fallback branch and your callback, but it cannot cover one element with another, so it can never prove occlusion. In deterministic tests, assert the application behavior you need instead.

Keep the minimum delay in shared configuration so a future browser or package update cannot quietly make the observer invalid.