thebuilder /react-intersection-observer
React implementation of the Intersection Observer API to tell you when an element enters or leaves the viewport.
★ 5,544⑂ 188👁 17⑃ 467● 266▤ 119
+1
日增长
5,544
stars
188
forks
17
watchers
467
prs
266
issues
119
releases
README
!npm package minimized gzipped size
A React implementation of the Intersection Observer API
that tells you when an element enters or leaves the viewport. Use it for scroll
animations, lazy loading, impression tracking, and infinite scroll. It ships
hooks, render props, and
plain children.
Features
- Hooks or component API - useInView for React state, useOnInView for
callbacks, for render props and wrapper elements.
- Shared observers - Observers with matching options are reused, so watching
many elements stays cheap.
- Matches the native API - Options map straight to
IntersectionObserverInit.
- Written in TypeScript - Types ship with the package.
- Ready to test - Mocks the Intersection Observer for
Jest and Vitest.
- Tree-shakeable - Only the parts you import end up in your bundle.
- Small - Around 1.15kB gzipped for useInView, 1.6kB for .
Installation
sh
npm install react-intersection-observer --save
Usage
useInView hook
js
// Use object destructuring, so you don't need to remember the exact order
const { ref, inView, entry } = useInView(options);
// Or array destructuring, making it easy to customize the field names
const [ref, inView, entry] = useInView(options);
Call useInView with the (optional) options you need. It returns a
ref, the inView status, and the current
entry.
Assign the ref to the DOM element you want to watch, and the hook reports the
status.
jsx
import React from "react";
import { useInView } from "react-intersection-observer";
const Component = () = {
const { ref, inView, entry } = useInView({
/ Optional options /
threshold: 0,
});
return (
{Header inside viewport ${inView}.}
);
};
Note: The first false notification from the underlying IntersectionObserver is ignored so your handlers only run after a real visibility change. Subsequent transitions still report both true and false states as the element enters and leaves the viewport.
useOnInView hook
js
const inViewRef = useOnInView(
(inView, entry) = {
if (inView) {
// Do something with the element that came into view
console.log("Element is in view", entry.target);
} else {
console.log("Element left view", entry.target);
}
},
options // Optional IntersectionObserver options
);
useOnInView takes a callback and returns a ref to assign to the DOM element
you want to watch. Whenever the element enters or leaves the viewport, the
callback runs with the latest in-view state.
Differences from useInView:
- No re-renders - The hook holds no state, so a visibility change never
triggers a render.
- Direct element access - The callback receives the
IntersectionObserverEntry, including the target element.
- Boolean-first callback - The first argument is the current inView
boolean, matching the onChange signature from useInView.
- Same options - Accepts every option useInView does, except
onChange, initialInView, and fallbackInView.
Note: Just like useInView, the initial fDiscussions
#739IntersectionObserverEntry is undefined until element is in view1 comments · 2025-12-07#704Can't make the mock working with vitest and react testing library0 comments · 2024-09-13#703When the child component calls the parent component's state, the state of isIntersecting is reset2 comments · 2024-09-11#700Is there an option to defer callback?1 comments · 2024-08-31#696ESLint error when importing from `test-utils`; Missing file extension `.mts`1 comments · 2024-08-06#683How to create a table of content using this library?0 comments · 2024-06-13#681Initially, element never changes inView state.0 comments · 2024-06-12#677Build fail due to type exports0 comments · 2024-05-30
Latest release
v11.0.1 v11.0.1 2026-08-26What's Changed Fix docs callouts and logo theming by @thebuilder in https://github.com/thebuilder/react-intersection-observer/pull/776 Agent/docs callouts and logo theme by @thebuilder in https://github.com/thebuilder/react-intersection-observer/pull/777 feat(docs): add custom landing page with scroll-driven intersection demos by @thebuilder in https://github.com/thebuilder/react-intersection-observer/pull/778 feat(docs): brand the generated OG cards to match the landing by @thebuilder in https://github.com/thebuilder/react-intersection-observer/pull/779 fix(docs): theme-aware landing pan