Share your code. npm Orgs help your team discover, share, and reuse code. Create a free org »

react-intersection-observer

5.0.5 • Public • Published

react-intersection-observer Version Badge

Build Status Coverage Statu dependency status dev dependency status License Downloads Greenkeeper badge styled with prettier

React component that triggers a function when the component enters or leaves the viewport. No complex configuration needed, just wrap your views and it handles the events.

Storybook demo: https://thebuilder.github.io/react-intersection-observer/

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

Child as function

The easiest way to use the Observer, is to pass a function as the child. It will be called whenever the state changes, with the new value of inView. By default it will render inside a <div>, but you can change the element by setting tag to the HTMLElement you need.

import Observer from 'react-intersection-observer'
 
const Component = () => (
  <Observer>
    {inView => <h2>{`Header inside viewport ${inView}.`}</h2>}
  </Observer>
)
 
export default Component

Render prop

Using the render prop you can get full control over the output. In addition to the inView prop, the render also receives a ref that should be set on the containing DOM element.

import Observer from 'react-intersection-observer'
 
const Component = () => (
  <Observer
    render={({ inView, ref }) => (
      <div ref={ref}>
        <h2>{`Header inside viewport ${inView}.`}</h2>
      </div>
    )}
  />
)
 
export default Component

OnChange callback

You can monitor the onChange method, and control the state in your own component. This works with plain children, child as function or render props.

import Observer from 'react-intersection-observer'
 
const Component = () => (
  <Observer onChange={inView => console.log('Inview:', inView)}>
    <h2>Plain children are always rendered. Use onChange to monitor state.</h2>
  </Observer>
)
 
export default Component

Props

The <Observer /> accepts the following props:

Name Type Default Required Description
children Func/Node false Children should be either a function or a node
render ({inView, ref}) => Node false Render prop allowing you to control the view.
root HTMLElement false The HTMLElement that is used as the viewport for checking visibility of the target. Defaults to the browser viewport if not specified or if null.
rootId String false Unique identifier for the root element - This is used to identify the IntersectionObserver instance, so it can be reused. If you defined a root element, without adding an id, it will create a new instance for all components.
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).
tag String 'div' false Element tag to use for the wrapping element when rendering using 'children'. Defaults to 'div'
threshold Number 0 false Number between 0 and 1 indicating the the percentage that should be visible before triggering. Can also be an array of numbers, to create multiple trigger points.
triggerOnce Bool false false Only trigger this method once
onChange Func 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:

loadPolyfills()
  .then(() => /* Render React application now that your Polyfills are ready */)
 
/**
* Do feature detection, to figure out which polyfills needs to be imported.
**/
function loadPolyfills() {
  const polyfills = []
 
  if (!supportsIntersectionObserver()) {
    polyfills.push(import('intersection-observer'))
  }
 
  return Promise.all(polyfills)
}
 
function supportsIntersectionObserver() {
  return (
    'IntersectionObserver' in global &&
    'IntersectionObserverEntry' in global &&
    'intersectionRatio' in IntersectionObserverEntry.prototype
  )
}

install

npm i react-intersection-observer

Downloadsweekly downloads

7,612

version

5.0.5

license

MIT

repository

githubgithub

last publish

collaborators

  • avatar