Repository files navigation

A React implementation of theIntersection Observer APIto tell you when an element enters or leaves the viewport. ContainsHooks,render props, andplain children implementations.

• 🪝Hooks or Component API - WithuseInView anduseOnInView it's easierthan ever to monitor elements
• ⚡️Optimized performance - Reuses Intersection Observer instances wherepossible
• ⚙️Matches native API - Intuitive to use
• 🛠Written in TypeScript - It'll fit right into your existing TypeScriptproject
• 🧪Ready to test - Mocks the Intersection Observer for easy testing withJest orVitest
• 🌳Tree-shakeable - Only include the parts you use
• 💥Tiny bundle - Around~1.15kB foruseInView and~1.6kB for<InView>

Install the package with your package manager of choice:

npm install react-intersection-observer --save

// Use object destructuring, so you don't need to remember the exact orderconst{ ref, inView, entry}=useInView(options);// Or array destructuring, making it easy to customize the field namesconst[ref,inView,entry]=useInView(options);

TheuseInView hook makes it easy to monitor theinView state of yourcomponents. Call theuseInView hook with the (optional)optionsyou need. It will return an array containing aref, theinView status andthe currententry.Assign theref to the DOM element you want to monitor, and the hook willreport the status.

importReactfrom"react";import{useInView}from"react-intersection-observer";constComponent=()=>{const{ ref, inView, entry}=useInView({/* Optional options */threshold:0,});return(<divref={ref}><h2>{`Header inside viewport${inView}.`}</h2></div>);};

Note: The firstfalse notification from the underlying IntersectionObserver is ignored so your handlers only run after a real visibility change. Subsequent transitions still report bothtrue andfalse states as the element enters and leaves the viewport.

constinViewRef=useOnInView((inView,entry)=>{if(inView){// Do something with the element that came into viewconsole.log("Element is in view",entry.target);}else{console.log("Element left view",entry.target);}},options// Optional IntersectionObserver options);

TheuseOnInView hook provides a more direct alternative touseInView. Ittakes a callback function and returns a ref that you can assign to the DOMelement you want to monitor. Whenever the element enters or leaves the viewport,your callback will be triggered with the latest in-view state.

Key differences fromuseInView:

• No re-renders - This hook doesn't update any state, making it ideal forperformance-critical scenarios
• Direct element access - Your callback receives the actualIntersectionObserverEntry with thetarget element
• Boolean-first callback - The callback receives the currentinViewboolean as the first argument, matching theonChange signature fromuseInView
• Similar options - Accepts all the sameoptions asuseInViewexceptonChange,initialInView, andfallbackInView

Note: Just likeuseInView, the initialfalse notification is skipped. Your callback fires the first time the element becomes visible (and on every subsequent enter/leave transition).

importReactfrom"react";import{useOnInView}from"react-intersection-observer";constComponent=()=>{// Track when element appears without causing re-rendersconsttrackingRef=useOnInView((inView,entry)=>{if(inView){// Element is in view - perhaps log an impressionconsole.log("Element appeared in view",entry.target);}else{console.log("Element left view",entry.target);}},{/* Optional options */threshold:0.5,triggerOnce:true,},);return(<divref={trackingRef}><h2>This element is being tracked without re-renders</h2></div>);};

To use the<InView> component, you pass it a function. It will be calledwhenever the state changes, with the new value ofinView. In addition to theinView prop, children also receive aref that should be set on thecontaining DOM element. This is the element that the Intersection Observer willmonitor.

If you need it, you can also access theIntersectionObserverEntryonentry, giving you access to all the details about the current intersectionstate.

import{InView}from"react-intersection-observer";constComponent=()=>(<InView>{({ inView, ref, entry})=>(<divref={ref}><h2>{`Header inside viewport${inView}.`}</h2></div>)}</InView>);exportdefaultComponent;

Note:<InView> mirrors the hook behaviour—it suppresses the very firstfalse notification so render props andonChange handlers only run after a genuine visibility change.

You can pass any element to the<InView />, and it will handle creating thewrapping DOM element. Add a handler to theonChange method, and control thestate in your own component. Any extra props you add to<InView> will bepassed to the HTML element, allowing you set theclassName,style, etc.

import{InView}from"react-intersection-observer";constComponent=()=>(<InViewas="div"onChange={(inView,entry)=>console.log("Inview:",inView)}><h2>Plain children are always rendered. Use onChange to monitor state.</h2></InView>);exportdefaultComponent;

Provide these as the options argument in theuseInView hook or as props on the<InView /> component.

useOnInView accepts the same options asuseInView exceptonChange,initialInView, andfallbackInView.

The<InView /> component also accepts the following props:

The newv2 implementation of IntersectionObserverextends the original API, so you can track if the element is covered by anotherelement or has filters applied to it. Useful for blocking clickjacking attemptsor tracking ad exposure.

To use it, you'll need to add the newtrackVisibility anddelay options.When you get theentry back, you can then monitor ifisVisible istrue.

constTrackVisible=()=>{const{ ref, entry}=useInView({trackVisibility:true,delay:100});return<divref={ref}>{entry?.isVisible}</div>;};

This is still a very new addition, so checkcaniuse for current browsersupport. IftrackVisibility has been set, and the current browser doesn'tsupport it, a fallback has been added to always reportisVisible astrue.

It's not added to the TypeScriptlib.d.ts file yet, so you will also have toextend theIntersectionObserverEntry with theisVisible boolean.

TheIntersectionObserver itself is just a simple but powerful tool. Here's afew ideas for how you can use it.

• Lazy image load
• Trigger animations
• Track impressions(Google Analytics, TagManager, etc.)

You can wrap multipleref assignments in a singleuseCallback:

importReact,{useRef,useCallback}from"react";import{useInView}from"react-intersection-observer";functionComponent(props){constref=useRef();const{ref:inViewRef, inView}=useInView();// Use `useCallback` so we don't recreate the function on each renderconstsetRefs=useCallback((node)=>{// Ref's from useRef needs to have the node assigned to `current`ref.current=node;// Callback refs, like the one from `useInView`, is a function that takes the node as an argumentinViewRef(node);},[inViewRef],);return<divref={setRefs}>Shared ref is visible:{inView}</div>;}

When usingrootMargin, the margin gets added to the currentroot - If yourapplication is running inside a<iframe>, or you have defined a customrootthis will not be the current viewport.

You can read more about this on these links:

• Intersection Observer API
• w3c/IntersectionObserver: rootMargin ignored within iframe
• w3c/IntersectionObserver: Cannot track intersection with an iframe's viewport
• w3c/Support iframe viewport tracking

In order to write meaningful tests, theIntersectionObserver needs to bemocked. You can use the includedreact-intersection-observer/test-utils tohelp with this. It mocks theIntersectionObserver, and includes a few methodsto assist with faking theinView state. When setting theisIntersectingvalue you can pass either aboolean value or a threshold between 0 and 1. Itwill emulate the real IntersectionObserver, allowing you to validate that yourcomponents are behaving as expected.

This library comes with built-in support for writing tests in bothJest andVitest

Testing with Jest should work out of the box. Just import thereact-intersection-observer/test-utils in your test files, and you can use themocking methods.

If you're running Vitest withglobals,then it'll automatically mock the IntersectionObserver, just like running withJest. Otherwise, you'll need to manually setup/reset the mocking in either theindividual tests, or asetup file.

import{vi,beforeEach,afterEach}from"vitest";import{setupIntersectionMocking,resetIntersectionMocking,}from"react-intersection-observer/test-utils";beforeEach(()=>{setupIntersectionMocking(vi.fn);});afterEach(()=>{resetIntersectionMocking();});

You only need to do this if the test environment does not supportbeforeEachglobally, alongside eitherjest.fn orvi.fn.

See the instructions forVitest. You should be able to use a similarsetup/reset code, adapted to the testing library you are using. Failing that,copy the code fromtest-utils.ts, and make your own version.

You can create aJest setup filethat leverages theunsupported fallbackoption. In this case, you can override theIntersectionObserver in test fileswere you actively importreact-intersection-observer/test-utils.

test-setup.js

import{defaultFallbackInView}from"react-intersection-observer";defaultFallbackInView(true);// or `false` - whichever consistent behavior makes the most sense for your use case.

Alternatively, you can mock the Intersection Observer in all tests with a globalsetup file. Addreact-intersection-observer/test-utils tosetupFilesAfterEnvin the Jest config, orsetupFiles inVitest.

module.exports={setupFilesAfterEnv:["react-intersection-observer/test-utils"],};

importReactfrom"react";import{screen,render}from"@testing-library/react";import{useInView}from"react-intersection-observer";import{mockAllIsIntersecting,mockIsIntersecting,intersectionMockInstance,}from"react-intersection-observer/test-utils";constHookComponent=({ options})=>{const{ ref, inView}=useInView(options);return(<divref={ref}data-testid="wrapper">{inView.toString()}</div>);};test("should create a hook inView",()=>{render(<HookComponent/>);// This causes all (existing) IntersectionObservers to be set as intersectingmockAllIsIntersecting(true);screen.getByText("true");});test("should create a hook inView with threshold",()=>{render(<HookComponentoptions={{threshold:0.3}}/>);mockAllIsIntersecting(0.1);screen.getByText("false");// Once the threshold has been passed, it will trigger inView.mockAllIsIntersecting(0.3);screen.getByText("true");});test("should mock intersecing on specific hook",()=>{render(<HookComponent/>);constwrapper=screen.getByTestId("wrapper");// Set the intersection state on the wrapper.mockIsIntersecting(wrapper,0.5);screen.getByText("true");});test("should create a hook and call observe",()=>{const{ getByTestId}=render(<HookComponent/>);constwrapper=getByTestId("wrapper");// Access the `IntersectionObserver` instance for the wrapper Element.constinstance=intersectionMockInstance(wrapper);expect(instance.observe).toHaveBeenCalledWith(wrapper);});

Intersection Observeris the API used to determine if an element is inside the viewport or not.Browser support is excellent -WithSafari adding support in 12.1,all major browsers now support Intersection Observers natively. Add thepolyfill, so it doesn't break on older versions of iOS and IE11.

If the client doesn't have support for theIntersectionObserver, then thedefault behavior is to throw an error. This will crash the React application,unless you capture it with an Error Boundary.

If you prefer, you can set a fallbackinView value to use if theIntersectionObserver doesn't exist. This will makereact-intersection-observer fail gracefully, but you must ensure yourapplication can correctly handle all your observers firing eithertrue orfalse at the same time.

You can set the fallback globally:

import{defaultFallbackInView}from"react-intersection-observer";defaultFallbackInView(true);// or 'false'

You can also define the fallback locally onuseInView or<InView> as anoption. This will override the global fallback value.

importReactfrom"react";import{useInView}from"react-intersection-observer";constComponent=()=>{const{ ref, inView, entry}=useInView({fallbackInView:true,});return(<divref={ref}><h2>{`Header inside viewport${inView}.`}</h2></div>);};

You can import thepolyfill directly or usea service likehttps://cdnjs.cloudflare.com/polyfill to add it whenneeded.

yarn add intersection-observer

Then import it in your app:

import"intersection-observer";

If you are using Webpack (or similar) you could usedynamic imports,to load the Polyfill only if needed. A basic implementation could look somethinglike this:

/** * Do feature detection, to figure out which polyfills needs to be imported. **/asyncfunctionloadPolyfills(){if(typeofwindow.IntersectionObserver==="undefined"){awaitimport("intersection-observer");}}

You can access theobserve method, thatreact-intersection-observer uses internally to create and destroyIntersectionObserver instances. This allows you to handle more advanced usecases, where you need full control over when and how observers are created.

import{observe}from"react-intersection-observer";constdestroy=observe(element,callback,options);

Theobserve method returns anunobserve function, that you must call inorder to destroy the observer again.