DOMIntermediateSSR-safehooks/dom/useIntersectionObserver.ts

useIntersectionObserver

Visibility / sentinel observing.

Import

TypeScript
import { useIntersectionObserver } from '@/hooks';

API

Signature

useIntersectionObserver(ref, options?) → entry?

When to use

Use useIntersectionObserver instead of re-implementing the same pattern in multiple components.

SSR / Next.js

Measurements are 0 / empty until the element is mounted.

Live playground

Edit the example and see it run against the real @/hooks package in this app.

Live playgroundEdit · run with real @/hooks · useIntersectionObserver
Editor
function Lazy() {
  const ref = useRef<HTMLDivElement>(null);
  const entry = useIntersectionObserver(ref, { threshold: 0.25 });
  return <div ref={ref}>{entry?.isIntersecting ? 'Visible' : 'Hidden'}</div>;
}
Preview

Implementation source

Full library source for useIntersectionObserver — copy into your project when you are not installing a package yet.

hooks/dom/useIntersectionObserver.ts
import { useEffect, useState } from 'react';
import type { RefObject } from 'react';
import { isBrowser } from '../utility/isBrowser';
import { useLatest } from '../utility/useLatest';

export interface UseIntersectionObserverOptions extends IntersectionObserverInit {
  freezeOnceVisible?: boolean;
  enabled?: boolean;
  onChange?: (entry: IntersectionObserverEntry) => void;
}

/** IntersectionObserver wrapper. */
export function useIntersectionObserver<T extends Element>(
  target: RefObject<T | null>,
  options: UseIntersectionObserverOptions = {},
): IntersectionObserverEntry | undefined {
  const {
    threshold = 0,
    root = null,
    rootMargin = '0%',
    freezeOnceVisible = false,
    enabled = true,
    onChange,
  } = options;

  const [entry, setEntry] = useState<IntersectionObserverEntry>();
  const frozen = freezeOnceVisible && entry?.isIntersecting;
  const onChangeRef = useLatest(onChange);

  useEffect(() => {
    if (!isBrowser() || !enabled || frozen || typeof IntersectionObserver === 'undefined') {
      return;
    }
    const el = target.current;
    if (!el) return;

    const observer = new IntersectionObserver(
      ([e]) => {
        if (!e) return;
        setEntry(e);
        onChangeRef.current?.(e);
      },
      { threshold, root, rootMargin },
    );

    observer.observe(el);
    return () => observer.disconnect();
  }, [target, threshold, root, rootMargin, enabled, frozen, onChangeRef]);

  return entry;
}

Copy-paste example

useIntersectionObserver.example.tsx
'use client';

import { useRef } from 'react';
import { useIntersectionObserver } from '@/hooks';

export function Lazy() {
  const ref = useRef<HTMLDivElement>(null);
  const entry = useIntersectionObserver(ref, { threshold: 0.25 });
  return <div ref={ref}>{entry?.isIntersecting ? 'Visible' : 'Hidden'}</div>;
}

Production checklist

  • Called only from Client Components or other custom hooks
  • Type parameters filled in (e.g. useFetch<User[]>)
  • Tip: Attach the ref before measuring. ResizeObserver requires a mounted element.
  • Source of truth: open hooks/dom/useIntersectionObserver.ts for implementation details