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]

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

Installation

Install the package with your package manager of choice:

npm install react-intersection-observer --save

Usage

useInView hook

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

import React from "react";
import { useInView } from "react-intersection-observer";

const Component = () => {
  const { ref, inView, entry } = useInView({
    /* Optional options */
    threshold: 0,
  });

  return (



      <h2>{`Header inside viewport ${inView}.`}</h2>



  );
};

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

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

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 (



      <h2>This element is being tracked without re-renders</h2>



  );
};

Render props

To use the <InView> 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.

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

 const Component = () => (
 <InView>
 {({ inView, ref, entry }) => (



        <h2>{`Header inside viewport ${inView}.`}</h2>



    )}
  </InView>
);

 export default Component;
 ```

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

### Plain children

You can pass any element to the `<InView />`, 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 `<InView>` will be
passed to the HTML element, allowing you set the `className`, `style`, etc.

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

const Component = () => (
  <InView as="div" onChange={(inView, entry) => console.log("Inview:", inView)}>
    <h2>Plain children are always rendered. Use onChange to monitor state.</h2>
  </InView>
);

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 <InView />. The component does not support Ref Forwarding, so if you need a ref to the HTML element, use the Render Props version instead.

API

Options

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

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

InView Props

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

Intersection Observer v2 🧪

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 a