use-intersection-observer

- Features
- Installation
- Usage
- Provide a ref from useRef
- Provide a DOM element
- API
- Why use this over react-intersection-observer
- Summary
- License

!npm bundle size

React implementation of the
intersection Observer Interface
to tell you when an element is visible in the viewport.

Demo: TODO Code Sandbox

Features

- Hooks API - Just provide a ref!
- Alternative Native-esque API - Pass an HTMLElement and an optional
function to handle IntersectionObserver callbacks.
- Performant - Intersections will not cause other observed elements to
re-render.
- Typed - Written with TypeScript!

Installation

Run the following:

``bash


Yarn

yarn add @asyarb/use-intersection-observer

NPM

npm i @asyarb/use-intersection-observer --save
`

Usage

$3

To observe the visibility of a component, pass a ref of that component to
useIntersectionObserver:

`jsx
const Example = () => {
const ref = useRef()

// Get the visibility boolean directly from the hook:
const inView = useIntersectionObserver({
ref,
options: {
threshold: 0.25,
triggerOnce: true,
},
})

useEffect(() => {
if (inView) {
// => Perform any side effect with it!
}
}, [inView])

return


}
`

inView will be updated whenever the observed element passes the specified
threshold.

Optionally, you can pass a callback function as the third parameter to perform
any side effect on intersection. This function receives the
IntersectionObserver entry (IntersectionObserverEntry) object as an
argument.

`jsx
const Example = () => {
const ref = useRef

// Pass an optional callback to perform side effects instead:
useIntersectionObserver({
ref,
callback: entry => console.log(entry.boundingClientRect),
})

return


}
`

$3

useIntersectionObserver can alternatively take an Element such as the return
value from document.querySelector().

`jsx
const element = document.querySelector('.someClass')

const Example = () => {
// Pass an HTMLElement directly:
const inView = useIntersectionObserver({ element })

return


}
`

Just like the ref examples, you can optionally provide a callback function.

API

| Argument | Description |
| ---------- | ------------------------------------------------------------------------------------------------------------------------------ |
| ref | React ref to observe. |
| element | Alternative HTML Element to observe. If both element and ref are defined, ref is prioritized. |
| options | IntersectionObserverOptions object with additional triggerOnce flag. |
| callback | Optional callback to fire on intersection. Receives the IntersectionObserverEntry object for the provided ref or element |

Why use this over react-intersection-observer

This package aims to prioritize performance for different use-cases.

react-intersection-observer utilizes a single IntersectionObserver instance
to observe all elements that use the useInView hook. By doing so, browsers can
batch IntersectionObserver callbacks together.

Conversely, this will cause any observered element's intersection to cause cause
_all_ observered components to re-render, not just itself. Even when using the
triggerOnce flag, components will still re-render post-intersection due to
callbacks still firing from a unified instance.

This package creates an IntersectionObserver instance for each unique
component that consumes the hook. This prevents the aforementioned issues at the
cost of additional overhead of creating an instance per element and losing
batched callbacks. This is remedied a bit by the triggerOnce flag as we can
disconnect instances entirely after intersection.

$3

If re-rendering your observered components are your most expensive operation, or
you just can't have re-rendering from other elements coming into view (e.g.
animations), consider using this package.

If callbacks are your most expensive operation during intersection,
react-intersection-observer` may be a better fit.

As always, try both and see what works best for your application.

License

MIT.