Skip to main content

useIntersectionObserver

Description and use case​

useIntersectionObserver exposes visibility state plus timing metrics for lazy loading and engagement tracking.

API signature​

function useIntersectionObserver<T extends Element = Element>(
  options?: IntersectionObserverInit
): UseIntersectionObserverReturn<T>

Parameters​

NameTypeRequiredDescription
optionsIntersectionObserverInitNoStandard root, rootMargin, and threshold observer options.

Return value​

FieldTypeDescription
ref(node: T | null) => voidCallback ref to attach to target element.
isVisiblebooleanWhether element currently satisfies intersection visibility threshold.
metrics.firstVisibleAtnumber | nullTimestamp of first visibility event.
metrics.totalVisibleMsnumberAccumulated visible duration across sessions.

Live interactive demo (StackBlitz)​

This demo uses an embedded StackBlitz sandbox. Load it inline or open it in a new tab.

Open demo in StackBlitz

Code example​

import {useIntersectionObserver} from 'react-perf-hooks';

export function HeroImage() {
  const {ref, isVisible, metrics} = useIntersectionObserver<HTMLImageElement>({
    threshold: 0.25,
    rootMargin: '150px 0px',
  });

  return (
    <figure>
      <img ref={ref} src={isVisible ? '/hero-large.jpg' : '/hero-placeholder.jpg'} alt="Hero" />
      <figcaption>
        First visible at: {metrics.firstVisibleAt?.toFixed(1) ?? 'n/a'}ms, total visible:{' '}
        {metrics.totalVisibleMs.toFixed(1)}ms
      </figcaption>
    </figure>
  );
}

Companion article​