Registry / web-framework / react-intersection-observer-hook

react-intersection-observer-hook

library4.0.2jsnpmunverified

The `react-intersection-observer-hook` package provides declarative React hooks, specifically `useIntersectionObserver` and `useTrackVisibility`, to interact with the browser's native Intersection Observer API. It simplifies detecting when a React component enters or exits the viewport, enabling features like lazy loading, infinite scrolling, and triggering animations. The current stable version is 4.0.2, with active development focusing on modern React compatibility, demonstrated by its recent update for React 19 in v4.0.0. Releases are frequent, addressing bugs and improving API ergonomics. Key differentiators include a dedicated `useTrackVisibility` for simpler boolean visibility checks, explicit `rootRef` handling for scrollable containers, and robust support for both ES Modules and CommonJS environments since v3.0.0, ensured through modern bundling practices.

web-framework

npm install react-intersection-observer-hook

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · REACT-INTERSECTION

react-intersection-observer-hook

web-frameworkjavascriptv4.0.2

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

useIntersectionObserver

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

✗ const useIntersectionObserver = require('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

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

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

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;

Debug

Known issues

breakingVersions `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.

affects: >=4.0.0

breakingVersion `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.

affects: >=3.0.0

gotchaThe `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.

affects: >=1.0.0

gotchaWhen 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>`.

affects: >=1.0.0

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

affects: >=4.0.2

Errors

Common errors & fixes

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

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.

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'

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

Upgrade

Version history

4.0.2latest on npm

Audit

Dependencies

reactrequiredRequired for all React hooks. Version 4.x explicitly requires React 19+ for ref cleanup functions.

react-domrequiredRequired for rendering and attaching refs in React applications. Version 4.x explicitly requires React 19+.

Agent activity

2 hits · last 30 days

node

Resources

githubhttps://github.com/onderonur/react-intersection-observer-hook ↗

packagehttps://www.npmjs.com/package/react-intersection-observer-hook ↗

homepagehttps://onderonur.github.io/react-intersection-observer-hook ↗