react-intersection-observer

React component that uses the IntersectionObserver API to tell you when an element enters or leaves the viewport. No complex configuration needed, just wrap your views and it handles the events.

Read the docs for more: https://react-intersection-observer.now.sh

Installation

Install using Yarn:

yarn add react-intersection-observer

or NPM:

npm install react-intersection-observer --save

⚠️ You also want to add the intersection-observer polyfill for full browser support. Check out adding the polyfill for details about how you can include it.

Usage

Hooks 🎣

🚨 Hooks are a new feature proposal that lets you use state and other React features without writing a class. They’re currently in React v16.7.0-alpha and being discussed in an open RFC. If you decide to use it in production, keep in mind that it may very well break.

The new Hooks feature, makes it even easier than before to monitor the inView state of your components. You can import the useInView hook, and pass it a ref to the DOM node you want to observe. It will then return true once the element enter the viewport.

It also accepts an options object, to control the Intersection Observer.

import { useRef } from 'react'
import { useInView } from 'react-intersection-observer'

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

  return (
    <div ref={ref}>
      <h2>{`Header inside viewport ${inView}.`}</h2>
    </div>
  )
}

If you need to know more details about the intersection, you can call the useIntersectionObserver hook instead. It takes the same input, but will return an object containing inView and intersection.

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 receives a ref that should be set on the containing DOM element. This is the element that the IntersectionObserver will monitor.

import { InView } from 'react-intersection-observer'

const Component = () => (
  <InView>
    {({ inView, ref }) => (
      <div ref={ref}>
        <h2>{`Header inside viewport ${inView}.`}</h2>
      </div>
    )}
  </InView>
)

export default Component

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. It will pass any extra props to the HTML element, allowing you set the className, style, etc.

import { InView } from 'react-intersection-observer'

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

export default Component

⚠️ When rendering a plain child, make sure you keep your HTML output semantic. Change the tag to match the context, and add a className to style the <InView />.

API

Options

Name	Type	Default	Required	Description
root	Element		false	The Element that is used as the viewport for checking visibility of the target. Defaults to the browser viewport (window) if not specified or if null.
rootMargin	string	'0px'	false	Margin around the root. Can have values similar to the CSS margin property, e.g. "10px 20px 30px 40px" (top, right, bottom, left).
threshold	number | number[]	0	false	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.
triggerOnce	boolean	false	false	Only trigger this method once

InView Props

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

Name	Type	Default	Required	Description
children	({inView, entry, ref}) => React.Node or React.Node		true	Children expects a function that receives an object contain an inView boolean and ref that should be assigned to the element root. Alternately pass a plain child, to have the <Observer /> deal with the wrapping element. You will also get the IntersectionObserverEntry as entry, giving you more details.
onChange	(inView, entry) => void		false	Call this function whenever the in view state changes

Usage in other projects

react-scroll-percentage

This module is used in react-scroll-percentage to monitor the scroll position of elements in view, useful for animating items as they become visible. This module is also a great example of using react-intersection-observer as the basis for more complex needs.

Intersection Observer

Intersection Observer is the API is used to determine if an element is inside the viewport or not. Browser support is pretty good, but Safari is still missing support.

Can i use intersectionobserver?

Polyfill

You can import the polyfill directly or use a service like polyfill.io to add it when needed.

yarn add intersection-observer

Then import it in your app:

import 'intersection-observer'

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

/**
 * Do feature detection, to figure out which polyfills needs to be imported.
 **/
async function loadPolyfills() {
  if (typeof window.IntersectionObserver === 'undefined') {
    await import('intersection-observer')
  }
}