useIntersectionObserver

Reactive wrapper around the IntersectionObserver API. Observes one or more elements for intersection changes with pause/resume/stop support. Targets can be Ref, MaybeElement, or a plain Element`.

Demo

Intersection Observer

false

rootMargin (px)

pause

↓ scroll down

target element

Usage

import { useRef$, useIntersectionObserver } from "@usels/core";

function Component() {
  const el$ = useRef$<HTMLDivElement>();

  const { isActive$, pause, resume } = useIntersectionObserver(
    el$,
    (entries) => {
      entries.forEach((entry) => {
        console.log(entry.isIntersecting);
      });
    },
    { threshold: 0.5 }
  );

  return <div ref={el$} />;
}

Threshold array

Trigger the callback at multiple intersection ratios:

useIntersectionObserver(el$, callback, {
  threshold: [0, 0.25, 0.5, 0.75, 1],
});

Custom root and rootMargin

useIntersectionObserver(el$, callback, {
  root: scrollContainerEl,
  rootMargin: "0px 0px -100px 0px",
});

Reactive root / rootMargin

Pass an Observable to reactively recreate the observer when the value changes:

const rootMargin$ = observable("0px");

useIntersectionObserver(el$, callback, { rootMargin: rootMargin$ });

// later — observer is automatically recreated with new margin
rootMargin$.set("-50px 0px");

Deferred start

Set immediate: false to start observation manually:

const { resume } = useIntersectionObserver(el$, callback, { immediate: false });

resume(); // starts observing

Pause and resume

const { pause, resume } = useIntersectionObserver(el$, callback);

pause(); // disconnects the observer, isActive$ → false
resume(); // reconnects the observer, isActive$ → true

Permanent stop

const { stop } = useIntersectionObserver(el$, callback);

stop(); // disconnects and prevents future resume()

Checking browser support

const { isSupported$ } = useIntersectionObserver(el$, callback);

console.log(isSupported$.get()); // Observable<boolean>

Type

Parameters

Parameter	Type	Description
target	MaybeEventTarget | MaybeEventTarget[]	-
callback	IntersectionObserverCallback	-
options	UseIntersectionObserverOptions (optional)	-

UseIntersectionObserverOptions

Option	Type	Default	Description
immediate	boolean	-	Whether to start observing immediately on mount. Default: true
root	MaybeEventTarget	-	The element or document used as the viewport. Default: browser viewport
rootMargin	string	-	Margin around the root. Accepts CSS-style values. Default: “0px”
threshold	number | number[]	-	Threshold(s) at which to trigger the callback. Default: 0

Returns

UseIntersectionObserverReturn

Name	Type	Description
stop	() => void	-
isSupported$	ReadonlyObservable<boolean>	-
isActive$	ReadonlyObservable<boolean>	-
pause	Fn	-
resume	Fn	-

Source

View on GitHub