React implementation of the intersection Observer Interface to tell you when an element is visible in the viewport.
- Hooks API - Provide a ref!
- Alternative Native-esque API - Pass an
HTMLElement
and an optional function to handleIntersectionObserver
callbacks. - Isolated - Intersections will not cause other observed elements to re-render.
- Typed - Written with TypeScript!
Run the following:
# Yarn
yarn add @asyarb/use-intersection-observer
# NPM
npm i @asyarb/use-intersection-observer --save
To observe the visibility of a component, pass a ref
of that component to
useIntersectionObserver
:
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 <div ref={ref}>Some content...</div>
}
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 list of
IntersectionObserver
entries (IntersectionObserverEntry[]
) array as an
argument.
const Example = () => {
const ref = useRef()
// Pass an optional callback to perform side effects instead:
useIntersectionObserver({
ref,
callback: entries => entries.forEach(e => console.log(e)),
})
return <div ref={ref}>Some content...</div>
}
useIntersectionObserver
can alternatively take an Element
such as the return
value from document.querySelector()
.
const element = document.querySelector('.someClass')
const Example = () => {
// Pass an HTMLElement directly:
const inView = useIntersectionObserver({ element })
return <div>Some content...</div>
}
Just like the ref
examples, you can optionally provide a callback function.
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 an additional triggerOnce argument. |
callback |
Optional callback to fire on intersection. Receives the array of IntersectionObserverEntry objects for the provided ref or element |
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.
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.
MIT.