# react-intersection-observer [![Version Badge][npm-version-svg]][package-url] [![GZipped size][npm-minzip-svg]][bundlephobia-url] [![Test][test-image]][test-url] [![License][license-image]][license-url] [![Downloads][downloads-image]][downloads-url] React implementation of the [Intersection Observer API](https://developer.mozilla.org/en-US/docs/Web/API/Intersection_Observer_API) to tell you when an element enters or leaves the viewport. Contains both a [Hooks](#useinview-hook), [render props](#render-props) and [plain children](#plain-children) implementation. ## Features - 🪝 **Hooks or Component API** - With `useInView` 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](https://jestjs.io/) or [Vitest](https://vitest.dev/) - 🌳 **Tree-shakeable** - Only include the parts you use - 💥 **Tiny bundle** - Around **~1.15kB** for `useInView` and **~1.6kB** for `` [![Open in StackBlitz](https://developer.stackblitz.com/img/open_in_stackblitz.svg)](https://stackblitz.com/github/thebuilder/react-intersection-observer) ## Installation Install the package with your package manager of choice: ```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); ``` The `useInView` hook makes it easy to monitor the `inView` state of your components. Call the `useInView` hook with the (optional) [options](#options) you need. It will return an array containing a `ref`, the `inView` status and the current [`entry`](https://developer.mozilla.org/en-US/docs/Web/API/IntersectionObserverEntry). 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 (

{`Header inside viewport ${inView}.`}

); }; ``` ### Render props 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`](https://developer.mozilla.org/en-US/docs/Web/API/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 }) => (

{`Header inside viewport ${inView}.`}

)} ); export default Component; ``` ### Plain children 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 ### Options 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()` | ### InView Props 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. | ### Intersection Observer v2 🧪 The new [v2 implementation of IntersectionObserver](https://developers.google.com/web/updates/2019/02/intersectionobserver-v2) 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

{entry?.isVisible}

; }; ``` This is still a very new addition, so check [caniuse](https://caniuse.com/#feat=intersectionobserver-v2) 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](docs/Recipes.md#lazy-image-load) - [Trigger animations](docs/Recipes.md#trigger-animations) - [Track impressions](docs/Recipes.md#track-impressions) _(Google Analytics, Tag Manager, etc.)_ ## FAQ ### How can I assign multiple refs to a component? 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

Shared ref is visible: {inView}

; } ``` ### `rootMargin` isn't working as expected When using `rootMargin`, the margin gets added to the current `root` - If your application is running inside a `

套件	下載數	Stars	大小	Issues	發布時間	許可

react-intersection-observer	2,450,811	5,326	132 kB	1	3 個月前	MIT