react-intersection-observer

react-intersection-observer wraps the browser’s native Intersection Observer API in idiomatic React primitives — the useInView hook, the lighter-weight useOnInView callback hook, and the <InView> render-props/wrapper component — so components can react to visibility changes without hand-rolling observer lifecycle management, cleanup, or SSR guards.

Under the hood, observers with matching root/rootMargin/threshold options are shared across instances, keeping memory and observer counts low even when hundreds of elements are being watched at once (image galleries, infinite feeds, animated sections). It ships full TypeScript types, built-in test mocks for Jest and Vitest, IntersectionObserver v2 support, and works across React 17 through 19.

What You Get

• Hooks API: useInView for React state-driven visibility, useOnInView for a lower-overhead callback-only variant that skips re-renders.
• An <InView> component supporting both a function-as-children render-props pattern and plain children with an onChange handler.
• Automatic observer sharing so many watched elements with identical options reuse a single native IntersectionObserver instance.
• Full TypeScript type definitions plus a test-utils entry point with mockAllIsIntersecting/intersectionMockInstance helpers for Jest and Vitest.
• Support for IntersectionObserver v2 (trackVisibility, delay) and a configurable fallbackInView for browsers without native support.

Common Use Cases

• Triggering scroll-based enter/exit animations as sections come into view.
• Lazy-loading images, iframes, or heavy components only once they’re about to be visible.
• Recording impression/analytics events the first time an element becomes visible using triggerOnce.
• Building infinite-scroll pagination by observing a sentinel element at the end of a list.
• Implementing reveal-on-scroll or sticky-header behavior tied to scroll position.

Under The Hood

Architecture

The package is a thin, layered wrapper: a single shared-state module (observe.ts) implements the observer registry (an observerMap keyed by a stringified options id from optionsToId), sitting beneath the consumer-facing primitives — useIntersectionObserverRef (the low-level ref/effect glue), useInView/useOnInView built on top of that ref, and the class-based InView component that calls observe() directly for its render-props/plain-children API. Data flows one way: a DOM ref registers a callback against a shared IntersectionObserver instance, the observer’s entries callback fans out to per-element callback lists, and hooks/InView translate that into React state or a passed onChange. The shared-observer pool is the core abstraction; if the options-to-id hashing or the pool’s cleanup logic broke, every consumer — hooks and component alike — would silently over- or under-observe elements. This is a clean, modular, single-responsibility layering with no framework or dependency-injection machinery, which suits a focused UI primitive.

Tech Stack

Written entirely in TypeScript, built with tsup into dual CJS/ESM output plus matching .d.ts/.d.mts type declarations, and validated post-build with arethetypeswrong and publint for package-export correctness, with bundle-size budgets enforced via size-limit. Its only peer dependencies are react and react-dom across a wide version range, with zero runtime dependencies of its own. The repository is a pnpm-workspace plus Turborepo monorepo, linted and formatted with Biome, and ships a separate Storybook and an Astro-based documentation site as sibling workspace packages. Tests run on Vitest, including a real-browser mode for genuine IntersectionObserver behavior rather than a mocked DOM.

Code Quality

Test coverage is extensive, spanning unit tests, an SSR-safety test, and real-browser scroll/intersection tests run through a browser-backed Vitest configuration. Types are strict with essentially no use of any outside a couple of explicitly justified escapes for a generic ref type. Naming is consistent throughout and exported functions carry documentation comments with runnable usage examples. Continuous integration runs the full test suite on every change, and pre-commit hooks run linting automatically. The one fallback code path — behavior when the native API is unsupported — is explicit, documented, and opt-in rather than silently swallowed.

API Design The public surface is intentionally small and layered by ergonomics: useInView returns a result destructurable as either an array or an object, letting callers pick whichever style fits their code; useOnInView exists purely to avoid a re-render for callback-only consumers; <InView> covers the non-hook case with both render-props and plain-children modes. Options mirror the native IntersectionObserverInit almost directly, plus a handful of well-justified additions such as triggerOnce, skip, and fallbackInView, keeping the learning curve close to zero for anyone who already knows the native API. Getting started requires no boilerplate beyond assigning a ref, and bundle size is continuously enforced to stay extremely small.