react-intersection-observer

[![Version Badge][npm-version-svg]][package-url]
[![GZipped size][npm-minzip-svg]][bundlephobia-url]
[![Build Status][travis-svg]][travis-url]
[![Coverage Statu][coveralls-svg]][coveralls-url]
[![dependency status][deps-svg]][deps-url]
[![dev dependency status][dev-deps-svg]][dev-deps-url]
[![License][license-image]][license-url]
[![Downloads][downloads-image]][downloads-url]
[![Greenkeeper badge][greenkeeper-svg]][greenkeeper-url]
[![styled with prettier][prettier-svg]][prettier-url]

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

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

Features

- 🎣 Hooks or Component API - With useInView it's easier than ever to
monitor elements
- ⚡️ Optimized performance - Auto reuses Intersection Observer instances
where possible
- ⚙️ Matches native API - Intuitive to use
- 🌳 Tree-shakeable - Only include the parts you use
- 💥 Tiny bundle [~1.9 kB gzipped][bundlephobia-url]

Installation

Install using Yarn:

``sh
yarn add react-intersection-observer
`

or NPM:

`sh
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

$3

#### useInView

`js
const [ref, inView, entry] = useInView(options)
`

The new React Hooks, makes it easier then ever 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
IntersectionObserverEntry.
Assign the ref to the DOM element you want to monitor, and the hook will
report the status.

`jsx
import React, { useRef } from 'react'
import { useInView } from 'react-intersection-observer'

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

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

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

const Component = () => (

{({ inView, ref }) => (


)}

)

export default Component
`

$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. It will pass any extra props 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
`

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

API

$3

Provide these as props on the component and as the options
argument for the hooks.

| Name | Type | Default | Required | Description |
| --------------- | ------------------ | ------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| root | Element | window | 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 |

$3

The component also accepts the following props:

| Name | Type | Default | Required | Description |
| ------------ | ------------------------- | ------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| as | string | 'div' | false | Render the wrapping element as this element. Defaults to div. |
| children | Function, ReactNode | | 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 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 |

Testing

In order to write meaningful tests, the IntersectionObserver needs to be
mocked. If you are writing your tests in Jest, you can use the included
test-utils.js. It mocks the IntersectionObserver, and includes a few methods
to assist with faking the inView state.

$3

Import the methods from react-intersection-observer/test-utils.

mockAllIsIntersecting(isIntersecting:boolean)
Set the isIntersecting on all current IntersectionObserver instances.

mockIsIntersecting(element:Element, isIntersecting:boolean)
Set the isIntersecting for the IntersectionObserver of a specific element.

intersectionMockInstance(element:Element): IntersectionObserver
Call the intersectionMockInstance method with an element, to get the (mocked)
IntersectionObserver instance. You can use this to spy on the observe and
unobserve methods.

$3

``js
import React from 'react'
import { render } from 'react-testing-library'
import { useInView } from 'react-intersection-observer'
import { mockAllIsIntersecting } from 'react-intersection-observer/test-utils'

const HookComponent = ({ options }) => {
const [ref, inView] = useInView(options)
return

}

test('should create a hook inView', () => {
const { getByText } = render()

// This causes all (existing) IntersectionObservers to be set as intersecting
mockAllIsIntersecting(true)
getByText('true')
})
`

Built using react-intersection-observer

$3

The new brand site for Sticks 'n' Sushi is filled with scroll based
animations. All of these are triggered by react-intersection-observer, with
react-scroll-percentage
controlling the animations.

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.



type="image/webp"
srcset="https://res.cloudinary.com/ireaderinokun/image/upload/v1549540370/caniuse-embed/intersectionobserver-2019-2-7.webp"
/>
type="image/png"
srcset="https://res.cloudinary.com/ireaderinokun/image/upload/v1549540370/caniuse-embed/intersectionobserver-2019-2-7.png"
/>
type="image/jpeg"
srcset="https://res.cloudinary.com/ireaderinokun/image/upload/v1549540370/caniuse-embed/intersectionobserver-2019-2-7.jpg"
/>
src="https://res.cloudinary.com/ireaderinokun/image/upload/v1549540370/caniuse-embed/intersectionobserver-2019-2-7.png"
alt="Data on support for the intersectionobserver feature across the major browsers from caniuse.com"
/>



$3

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

`sh
yarn add intersection-observer
`

Then import it in your app:

`js
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:

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

[package-url]: https://npmjs.org/package/react-intersection-observer
[npm-version-svg]: https://img.shields.io/npm/v/react-intersection-observer.svg
[npm-minzip-svg]: https://img.shields.io/bundlephobia/minzip/react.svg
[bundlephobia-url]:
https://bundlephobia.com/result?p=react-intersection-observer
[travis-svg]: https://travis-ci.org/thebuilder/react-intersection-observer.svg
[travis-url]: https://travis-ci.org/thebuilder/react-intersection-observer
[coveralls-svg]:
https://coveralls.io/repos/github/thebuilder/react-intersection-observer/badge.svg?branch=master
[coveralls-url]:
https://coveralls.io/github/thebuilder/react-intersection-observer?branch=master
[deps-svg]: https://david-dm.org/thebuilder/react-intersection-observer.svg
[deps-url]: https://david-dm.org/thebuilder/react-intersection-observer
[dev-deps-svg]:
https://david-dm.org/thebuilder/react-intersection-observer/dev-status.svg
[dev-deps-url]:
https://david-dm.org/thebuilder/react-intersection-observer#info=devDependencies
[license-image]: http://img.shields.io/npm/l/react-intersection-observer.svg
[license-url]: LICENSE
[downloads-image]: http://img.shields.io/npm/dm/react-intersection-observer.svg
[downloads-url]:
http://npm-stat.com/charts.html?package=react-intersection-observer
[greenkeeper-svg]:
https://badges.greenkeeper.io/thebuilder/react-intersection-observer.svg
[greenkeeper-url]: https://greenkeeper.io/
[prettier-svg]: https://img.shields.io/badge/styled_with-prettier-ff69b4.svg
[prettier-url]: https://github.com/prettier/prettier