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 · useIntersectionObserverEditor
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.tsfor implementation details