react-peekaboo
React hooks for monitoring an element's intersection with the viewport.
Installation
npm install react-peekaboo
Usage
import React, { useState } from 'react';
import { useIntersecting, useIntersectionChange } from 'react-peekaboo';
function UseIntersectionExample() {
let [ref, isIntersecting] = useIntersecting<HTMLDivElement>();
return (
<div ref={ref}>I am {isIntersecting ? 'visible' : 'not visible'}.</div>
);
}
function UseIntersectionChangeExample() {
let [isIntersecting, onChange] = useState<boolean>(false);
let ref = useIntersectionChange<HTMLDivElement>(onChange);
return (
<div ref={ref}>I am {isIntersecting ? 'visible' : 'not visible'}.</div>
);
}
API
Options
All functions accept a common set of options:
-
enabled?: boolean
: Enables/disables running the side effect that calculates
the element's intersection status. (default: true
)
-
offsetBottom?: number
: Number of pixels to add to the bottom of the area
checked against when computing element intersection. (default: 0
)
-
offsetLeft?: number
: Number of pixels to add to the left of the area checked
against when computing element intersection. (default: 0
)
-
offsetRight?: number
: Number of pixels to add to the right of the area
checked against when computing element intersection. (default: 0
)
-
offsetTop?: number
: Number of pixels to add to the top of the area checked
against when computing element intersection. (default: 0
)
-
throttle?: number
: Number of ms to throttle scroll events (only applies in
environments that don't support IntersectionObserver or when using
useScrollIntersection
/useScrollIntersectionChangeCallback
). (default:
100
)
Exports
useIntersecting
Type: (options: Options) => [RefCallback, boolean]
Returns a ref and the element's intersection status using IntersectionObserver
or scroll
/resize
event listeners and getBoundingClientRect
in unsupported
environments.
The ref returned must be attached to a DOM node.
useIntersectionChange
Type:
(onChange: (isIntersecting: boolean) => void, options: Options) => RefCallback;
Runs a callback that receives the element's intersection status each time it
changes using IntersectionObserver or scroll
/resize
event listeners and
getBoundingClientRect
in unsupported environments.
Returns a ref that must be attached to a DOM node.
usePeekaboo
Type:
type SetupHandler = (
element: HTMLElement,
onChange: (isIntersecting: boolean) => void,
options?: Options,
) => TeardownHandler;
(
setup: SetupHandler,
onChange: (isIntersecting: boolean) => void,
options?: Options,
) => RefCallback;
Uses setup
to run onChange
when the element's intersection status changes.
You can pass scroll
, io
, or peekaboo
from dom-peekaboo
or implement our
own setup function.