React Intersection Observer Hook

Common errors

• TypeError: Cannot read properties of undefined (reading 'isIntersecting')

  cause The `entry` object from `useIntersectionObserver` or `useTrackVisibility` is `undefined` during the initial render before the observer has reported an intersection.
  fix Always guard access to `entry` properties, e.g., `const isVisible = entry && entry.isIntersecting;`.

• Error: Invalid hook call. Hooks can only be called inside of the body of a function component.

  cause Using `useIntersectionObserver` or `useTrackVisibility` outside a React function component or custom hook, or having multiple React versions in your dependency tree.
  fix Ensure the hook is called within a React function component or another custom hook, and verify `react` and `react-dom` peer dependencies match your project's React version (especially for v4 requiring React 19).

• Module not found: Can't resolve 'react-intersection-observer-hook'

  cause Your build tool or Node.js environment is struggling to resolve the package's module exports, potentially due to `v3.0.0`'s bundling changes and stricter ESM/CJS output.
  fix Check your `tsconfig.json` (`moduleResolution`, `module`), `package.json` (`type`), and bundler configuration. Ensure you're using a modern bundler setup that supports `exports` field in `package.json`.

Warnings

• breaking Versions `v4.0.0` and above are designed for React 19 and utilize its new cleanup functions for refs. Users on older React versions (e.g., React 18 or earlier) should continue using `v3.x` to avoid compatibility issues.
  Fix: Upgrade your project's React and React-DOM peer dependencies to v19 or higher, or explicitly install `react-intersection-observer-hook@^3` if you need to remain on an older React version.
• breaking Version `v3.0.0` introduced significant internal changes, including a migration to a monorepo structure, bundling with tsup, and stricter ESM/CJS compliance. While this improves module support, users with highly customized or older build setups might encounter resolution issues.
  Fix: Ensure your bundler (e.g., Webpack, Rollup, Vite) is configured to handle modern ES Modules and CommonJS interoperability correctly. Check `publint` and `Are the Types Wrong` documentation if module resolution issues persist.
• gotcha The `ref` callback returned by `useIntersectionObserver` and `useTrackVisibility` must be attached to *only one* element at a time. Attaching it to multiple elements will result in unexpected behavior or only track the last assigned element.
  Fix: If tracking multiple elements, use separate `useIntersectionObserver` instances for each, or manage multiple refs manually with a single observer if advanced control is needed.
• gotcha When specifying a scrollable container as the `root`, the `rootRef` callback returned by the hook should be used to assign the container element, rather than attempting to pass a `root` DOM element directly as an argument to the hook.
  Fix: Use the `rootRef` callback from the hook: `<ScrollableContainer ref={rootRef}><SomeComponent ref={ref}/></ScrollableContainer>`.
• deprecated As of `v4.0.2`, the README no longer suggests using a polyfill for `IntersectionObserver`. Modern browsers widely support the API, and polyfills are rarely needed unless targeting legacy environments.
  Fix: Unless targeting extremely old browsers, avoid including `IntersectionObserver` polyfills to reduce bundle size and potential conflicts.

Install

• npm install react-intersection-observer-hook npm
• yarn add react-intersection-observer-hook yarn
• pnpm add react-intersection-observer-hook pnpm

Imports

• useIntersectionObserver
  wrong:

  const useIntersectionObserver = require('react-intersection-observer-hook');

  correct:

  import { useIntersectionObserver } from 'react-intersection-observer-hook';

  This package is ESM-first since v3.0.0. Use ES module `import` syntax. `require()` might cause issues with some bundlers.
• useTrackVisibility
  wrong:

  import useTrackVisibility from 'react-intersection-observer-hook';

  correct:

  import { useTrackVisibility } from 'react-intersection-observer-hook';

  `useTrackVisibility` is a named export, not a default export. Ensure correct named import syntax.
• IntersectionObserverHookArgs

  import type { IntersectionObserverHookArgs } from 'react-intersection-observer-hook';

  Import types separately using `import type` for better type-checking and bundle optimization in TypeScript projects.

Quickstart

This example demonstrates how to use `useTrackVisibility` to detect when a component enters or leaves the viewport, changing its background color. It also shows how to specify a custom scrollable container using `rootRef`.

import React from 'react';
import { useTrackVisibility } from 'react-intersection-observer-hook';

function MyTrackedComponent() {
  const [ref, { isVisible, entry, rootRef }] = useTrackVisibility({
    // Optionally, track visibility only once
    // once: true,
    // Customize intersection threshold (0.0 to 1.0)
    threshold: 0.5,
    // Add margin around the root (e.g., '10px 20px 30px 40px')
    // rootMargin: '0px 0px -50px 0px',
  });

  // For a scrollable container (e.g., div with overflow-y: scroll),
  // attach rootRef to the container. Otherwise, it defaults to the viewport.
  const ScrollableContainer = React.forwardRef((props, forwardedRef) => (
    <div ref={forwardedRef} style={{ height: '300px', overflowY: 'scroll', border: '1px solid gray' }}>
      {props.children}
    </div>
  ));

  return (
    <div style={{ height: '1000px', padding: '200px 0' }}>
      <p>Scroll down to see the tracked element.</p>
      <ScrollableContainer ref={rootRef}>
        <div style={{ height: '400px', background: 'lightblue', margin: '100px 0' }}></div>
        <div ref={ref} style={{ height: '200px', background: isVisible ? 'lightgreen' : 'lightcoral', display: 'flex', alignItems: 'center', justifyContent: 'center' }}>
          <h2>Element is {isVisible ? 'visible!' : 'not visible.'}</h2>
          {entry && <p>Intersection Ratio: {entry.intersectionRatio.toFixed(2)}</p>}
        </div>
        <div style={{ height: '400px', background: 'lightblue', margin: '100px 0' }}></div>
      </ScrollableContainer>
    </div>
  );
}

export default MyTrackedComponent;