react-intersection-observer

[![Version Badge][npm-version-svg]][package-url]
[![Test][test-image]][test-url]
[![License][license-image]][license-url]
[![Downloads][downloads-image]][downloads-url]
!npm package minimized gzipped size

A React implementation of the Intersection Observer API
to tell you when an element enters or leaves the viewport. Contains Hooks, render props, and plain children implementations.

Features

- 🪝 Hooks or Component API - With useInView and useOnInView it's easier
than ever to monitor elements
- ⚡️ Optimized performance - Reuses Intersection Observer instances where
possible
- ⚙️ Matches native API - Intuitive to use
- 🛠 Written in TypeScript - It'll fit right into your existing TypeScript
project
- 🧪 Ready to test - Mocks the Intersection Observer for easy testing with
Jest or Vitest
- 🌳 Tree-shakeable - Only include the parts you use
- 💥 Tiny bundle - Around ~1.15kB for useInView and ~1.6kB for
!useInView !InView
!useOnInView


Installation

Install the package with your package manager of choice:

``sh
npm install react-intersection-observer --save
`

Usage

$3

`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);
`

The useInView hook makes it easy to monitor the inView state of your
components. Call the useInView hook with the (optional) options
you need. It will return an array containing a ref, the inView status and
the current
entry.
Assign the ref to the DOM element you want to monitor, and the hook will
report 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 (



);
};
`

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

$3

`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
);
`

The useOnInView hook provides a more direct alternative to useInView. It
takes a callback function and returns a ref that you can assign to the DOM
element 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 from useInView:
- No re-renders - This hook doesn't update any state, making it ideal for
performance-critical scenarios
- Direct element access - Your callback receives the actual
IntersectionObserverEntry with the target element
- Boolean-first callback - The callback receives the current inView
boolean as the first argument, matching the onChange signature from
useInView
- Similar options - Accepts all the same options as useInView
except onChange, initialInView, and fallbackInView

> Note: Just like useInView, the initial false notification is skipped. Your callback fires the first time the element becomes visible (and on every subsequent enter/leave transition).

`jsx
import React from "react";
import { useOnInView } from "react-intersection-observer";

const Component = () => {
// Track when element appears without causing re-renders
const trackingRef = useOnInView(
(inView, entry) => {
if (inView) {
// Element is in view - perhaps log an impression
console.log("Element appeared in view", entry.target);
} else {
console.log("Element left view", entry.target);
}
},
{
/ Optional options /
threshold: 0.5,
triggerOnce: true,
},
);

return (



);
};
`

$3

To use the component, you pass it a function. It will be called
whenever the state changes, with the new value of inView. In addition to the
inView prop, children also receive a ref that should be set on the
containing DOM element. This is the element that the Intersection Observer will
monitor.

If you need it, you can also access the
IntersectionObserverEntry
on entry, giving you access to all the details about the current intersection
state.

`jsx
import { InView } from "react-intersection-observer";

const Component = () => (

{({ inView, ref, entry }) => (


)}

);

export default Component;
`

> Note: mirrors the hook behaviour—it suppresses the very first false notification so render props and onChange handlers only run after a genuine visibility change.

$3

You can pass any element to the , and it will handle creating the
wrapping DOM element. Add a handler to the onChange method, and control the
state in your own component. Any extra props you add to will be
passed to the HTML element, allowing you set the className, style, etc.

`jsx
import { InView } from "react-intersection-observer";

const Component = () => (
console.log("Inview:", inView)}>


Plain children are always rendered. Use onChange to monitor state.

);

export default Component;
`

> [!NOTE]
> When rendering a plain child, make sure you keep your HTML output
> semantic. Change the as to match the context, and add a className to style
> the . The component does not support Ref Forwarding, so if you
> need a ref to the HTML element, use the Render Props version instead.

API

$3

Provide these as the options argument in the useInView hook or as props on the
component.

| Name | Type | Default | Description |
| ---------------------- | ------------------------- | ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| root | Element | document | The Intersection Observer interface's read-only root property identifies the Element or Document whose bounds are treated as the bounding box of the viewport for the element which is the observer's target. If the root is null, then the bounds of the actual document viewport are used. |
| rootMargin | string | '0px' | Margin around the root. Can have values similar to the CSS margin property, e.g. "10px 20px 30px 40px" (top, right, bottom, left). Also supports percentages, to check if an element intersects with the center of the viewport for example "-50% 0% -50% 0%". |
| threshold | number or number[] | 0 | Number between 0 and 1 indicating the percentage that should be visible before triggering. Can also be an array of numbers, to create multiple trigger points. |
| onChange | (inView, entry) => void | undefined | Call this function whenever the in view state changes. It will receive the inView boolean, alongside the current IntersectionObserverEntry. |
| trackVisibility 🧪 | boolean | false | A boolean indicating whether this Intersection Observer will track visibility changes on the target. |
| delay 🧪 | number | undefined | A number indicating the minimum delay in milliseconds between notifications from this observer for a given target. This must be set to at least 100 if trackVisibility is true. |
| skip | boolean | false | Skip creating the IntersectionObserver. You can use this to enable and disable the observer as needed. If skip is set while inView, the current state will still be kept. |
| triggerOnce | boolean | false | Only trigger the observer once. |
| initialInView | boolean | false | Set the initial value of the inView boolean. This can be used if you expect the element to be in the viewport to start with, and you want to trigger something when it leaves. |
| fallbackInView | boolean | undefined | If the IntersectionObserver API isn't available in the client, the default behavior is to throw an Error. You can set a specific fallback behavior, and the inView value will be set to this instead of failing. To set a global default, you can set it with the defaultFallbackInView() |

useOnInView accepts the same options as useInView except onChange,
initialInView, and fallbackInView.

$3

The component also accepts the following props:

| Name | Type | Default | Description |
| ------------ | ---------------------------------------------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| as | IntrinsicElement | 'div' | Render the wrapping element as this element. Defaults to div. If you want to use a custom component, please use the useInView hook or a render prop instead to manage the reference explictly. |
| children | ({ref, inView, entry}) => ReactNode or ReactNode | undefined | Children expects a function that receives an object containing the inView boolean and a ref that should be assigned to the element root. Alternatively pass a plain child, to have the deal with the wrapping element. You will also get the IntersectionObserverEntry as entry, giving you more details. |

$3

The new
v2 implementation of IntersectionObserver
extends the original API, so you can track if the element is covered by another
element or has filters applied to it. Useful for blocking clickjacking attempts
or tracking ad exposure.

To use it, you'll need to add the new trackVisibility and delay options.
When you get the entry back, you can then monitor if isVisible is true.

`jsx
const TrackVisible = () => {
const { ref, entry } = useInView({ trackVisibility: true, delay: 100 });
return

;
};
`

This is still a very new addition, so check
caniuse for current browser
support. If trackVisibility has been set, and the current browser doesn't
support it, a fallback has been added to always report isVisible as true.

It's not added to the TypeScript lib.d.ts file yet, so you will also have to
extend the IntersectionObserverEntry with the isVisible boolean.

Recipes

The IntersectionObserver itself is just a simple but powerful tool. Here's a
few ideas for how you can use it.

- Lazy image load
- Trigger animations
- Track impressions _(Google Analytics, Tag
Manager, etc.)_

FAQ

$3

You can wrap multiple ref assignments in a single useCallback:

`jsx
import React, { useRef, useCallback } from "react";
import { useInView } from "react-intersection-observer";

function Component(props) {
const ref = useRef();
const { ref: inViewRef, inView } = useInView();

// Use useCallback so we don't recreate the function on each render
const setRefs = 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 argument
inViewRef(node);
},
[inViewRef],
);

return

;
}
`

$3

When using rootMargin, the margin gets added to the current root - If your
application is running inside a