## Introduction: Why IntersectionObserver Matters For years, "is this element visible?" meant scroll listeners. You'd attach a listener to `window` or a scroll container, and on every scroll you'd call `getBoundingClientRect()` on one or more elements to see if they were in view. That approach works, but it has serious downsides: scroll events fire very often, and reading layout (e.g. `getBoundingClientRect()`) can force the browser to recalculate layout repeatedly. The result is jank, especially on long pages with many elements to check. **IntersectionObserver** is a browser API that solves this. You tell the browser which elements to watch and what "visible" means (viewport, or a custom root, with optional margins and thresholds). The browser then notifies you when those elements intersect the root—without you listening to scroll or touching layout in a hot path. The browser can batch and optimize the work. Your code becomes simpler and your pages smoother. Use cases include: - **Lazy loading:** Load images or components when they're about to enter the viewport. - **Infinite scroll:** Detect when a sentinel element is visible and load more content. - **Scroll-triggered animations:** Run animations or add classes when sections come into view. - **Sticky headers / visibility toggles:** Know when a section has scrolled past to change header style or show a "back to top" button. - **Analytics:** Record when content is actually seen (read time, ad visibility). By the end of this guide you will: - Understand what IntersectionObserver is and when to use it - Know the API: constructor, options (`root`, `rootMargin`, `threshold`), and callback - Use it correctly in React: refs, `useEffect`, and cleanup - Build a reusable `useIntersectionObserver` hook - Apply it to lazy loading, infinite scroll, animations, and analytics - Avoid common pitfalls (cleanup, SSR, ref timing) Examples in this guide use **TypeScript** so you can see how to type the observer options, callback entries, and a reusable hook (e.g. `RefObject`, `IntersectionObserverEntry`). The API is the same in JavaScript; the types make it clear what the browser gives you and how to use it safely in React. Because the observer needs a DOM element to observe, using it in React goes hand-in-hand with **refs**: you store the observer in a ref, attach a ref to the target element, and set up the observer in an effect. If you're new to refs, the [React Refs deep dive](/posts/2026/react/react-refs-the-complete-deep-dive) on this site covers them in detail. --- ## What Is IntersectionObserver? IntersectionObserver is a **browser API** that notifies you when a target element's visibility relative to a "root" (usually the viewport) crosses thresholds you specify. You create an observer with a callback and options, then call `observe(target)` for each element you want to watch. When intersection state changes (e.g. the element enters or leaves the viewport), the browser invokes your callback with entries describing what changed. Key ideas: - **Asynchronous:** The browser decides when to run your callback; you don't poll or listen to scroll. - **Root:** The rectangle used for comparison—default is the viewport; you can use another scroll container. - **Threshold:** At what ratio of visibility (0 to 1) the callback runs (e.g. 0.5 = 50% visible). - **rootMargin:** Expand or shrink the root (like CSS margin), so you can trigger "when the element is 100px from entering the viewport." You get one callback per observer, and each entry tells you which target changed and its intersection state. That's enough to implement lazy loading, infinite scroll, and scroll-driven UI. --- ## The API in Detail ### Constructor ```ts const observer = new IntersectionObserver(callback, options); ``` - **callback:** Function called when observed elements cross the configured thresholds. It receives two arguments: an array of `IntersectionObserverEntry` objects and the observer itself. In TypeScript the signature is `(entries: IntersectionObserverEntry[], observer: IntersectionObserver) => void`. - **options:** Optional object of type `IntersectionObserverInit` with `root`, `rootMargin`, and `threshold` (described below). ### Methods **observe(target)** Start observing a DOM element. ```ts observer.observe(document.querySelector('.my-element')!); ``` **unobserve(target)** Stop observing an element. The callback will no longer be called for this target. ```ts observer.unobserve(element); ``` **disconnect()** Stop observing all targets. Use this when the component unmounts or you no longer need the observer. ```ts observer.disconnect(); ``` **takeRecords()** Returns any pending entries that haven't been delivered to the callback yet. Rarely needed; useful if you're disconnecting and want to process remaining entries synchronously. ```ts const entries: IntersectionObserverEntry[] = observer.takeRecords(); ``` ### Options Object The options object is typed as `IntersectionObserverInit` in TypeScript: ```ts const options: IntersectionObserverInit = { root: null, // null = viewport; or an Element (e.g. scroll container) rootMargin: '0px', // CSS-like margin: "10px 0px 20px 0px" or "0px" threshold: 0 // number 0–1 or array of numbers }; ``` We'll go through each option in the next section. --- ## Options: root, rootMargin, threshold These three options define *when* your callback runs and *what* counts as "intersecting." ### root - **Default:** `null`, meaning the browser's viewport. - **Or:** A DOM element that acts as the scroll container. The intersection is computed between the target and this element's bounding box (not the viewport). Use a custom `root` when you're observing visibility inside a scrollable div, not the window: ```ts const scrollContainer = document.querySelector('.scroll-container'); const observer = new IntersectionObserver(callback, { root: scrollContainer, threshold: 0.5 }); observer.observe(scrollContainer!.querySelector('.item')!); ``` The target must be a descendant of `root` (or the root itself). If `root` is `null`, the intersection is with the viewport. ### rootMargin - **Default:** `"0px"`. - **Format:** Same as CSS margin: one value (all sides), two (vertical horizontal), or four (top right bottom left). You can use negative values to shrink the effective root. `rootMargin` expands or shrinks the rectangle used for intersection. Positive margin makes the "root" larger, so the callback can fire when the target is still outside the visible area (e.g. 100px below the viewport). Negative margin shrinks it, so the target must be more "inside" to count. Examples: ```ts // Fire when target is 100px away from entering the viewport (below) rootMargin: '100px 0px 100px 0px' // top right bottom left // Shorthand: 100px on top and bottom rootMargin: '100px 0px' // Fire only when 50px of the target is inside the viewport (shrink root) rootMargin: '-50px 0px' ``` Common use: lazy loading with `rootMargin: '200px'` so images start loading just before they scroll into view. ### threshold - **Default:** `0` (callback when a single pixel is visible). - **Value:** A number between 0 and 1, or an array of such numbers. `threshold` is the **ratio of the target that must be visible** (intersecting the root) for the callback to run. It's the area of intersection divided by the area of the target (or similar; the spec uses a more precise definition, but "how much of the target is visible" is the idea). - `0`: Callback when any part of the target enters or leaves. - `0.5`: Callback when 50% of the target is visible (and when it crosses that point). - `1`: Callback when 100% of the target is visible. - `[0, 0.25, 0.5, 0.75, 1]`: Callback at each of those visibility levels. Example: ```ts const observer = new IntersectionObserver((entries: IntersectionObserverEntry[]) => { entries.forEach((entry) => { console.log(entry.intersectionRatio); // 0, 0.25, 0.5, 0.75, or 1 }); }, { threshold: [0, 0.25, 0.5, 0.75, 1] }); ``` --- ## The Callback and IntersectionObserverEntry Your callback receives two arguments. In TypeScript you can type them explicitly; the DOM lib includes `IntersectionObserverEntry`: ```ts function callback(entries: IntersectionObserverEntry[], observer: IntersectionObserver): void { entries.forEach((entry) => { // entry is an IntersectionObserverEntry }); } ``` ### entries An array of **IntersectionObserverEntry** objects. Usually there's one entry per callback invocation when a single element crosses a threshold; when multiple elements cross at once (e.g. during a fast scroll), you may get multiple entries. Always iterate. ### IntersectionObserverEntry properties | Property | Description | |----------|-------------| | `target` | The observed DOM element | | `intersectionRatio` | Ratio of target visible (0–1) | | `isIntersecting` | `true` if target is intersecting the root (ratio > 0) | | `boundingClientRect` | Target's bounding rect (like `getBoundingClientRect()`) | | `intersectionRect` | The rectangle of the intersection | | `rootBounds` | Bounding rect of the root (null if root is not attached) | | `time` | Timestamp when the intersection was computed | **isIntersecting** is the property you'll use most often: "has the element entered the viewport?" (or crossed into the root with the given rootMargin). It's `true` when `intersectionRatio > 0` and `false` when it's 0. For lazy loading or "run once when visible," you typically check `entry.isIntersecting`. **intersectionRatio** is useful when you need the exact visibility (e.g. "animate opacity based on how much is visible" or "trigger at 50% visible"). ### When the callback runs The callback runs: - When an observed element crosses a threshold (e.g. from 0 to 0.5, or 0.5 to 0). - Optionally once at the start when you call `observe()` (the browser may deliver an initial entry with the current intersection state). So you might get an entry with `isIntersecting: true` as soon as you observe an element that's already on screen, and again when it leaves. Handle both "entering" and "leaving" if your logic depends on it (e.g. pause video when not visible). ### observer argument The second parameter is the same IntersectionObserver instance. Useful if you want to call `unobserve(entry.target)` inside the callback (e.g. "load once, then stop observing"): ```ts const observer = new IntersectionObserver( (entries: IntersectionObserverEntry[], obs: IntersectionObserver) => { entries.forEach((entry) => { if (entry.isIntersecting) { loadContent(entry.target); obs.unobserve(entry.target); } }); }, { rootMargin: '100px' } ); ``` --- ## Using IntersectionObserver in React In React you don't create observers in render or store DOM nodes in state. You use **refs** to hold both the observer instance and the target element, and you create/clean up the observer in **useEffect**. ### Why refs and useEffect? - **Target element:** You need a DOM node to pass to `observe()`. That node is available only after the component mounts. A ref attached to the element (e.g. `

`) gets set by React when the element is mounted and cleared when it unmounts. So you use a ref for the target. - **Observer instance:** The observer is created once and must be the same across re-renders. If you created it in render you'd get a new observer every time. Storing it in a ref (or in a variable inside useEffect) keeps it stable. Creating it in useEffect also gives you a single place to call `disconnect()` in the cleanup. - **Cleanup:** When the component unmounts or the target changes, you must call `unobserve()` and/or `disconnect()` to avoid leaks and unnecessary callbacks. useEffect's return function is the right place. So: **ref for the target, ref (or local variable) for the observer, setup and teardown in useEffect.** ### Basic pattern ```tsx function LazySection() { const targetRef = useRef(null); const [isVisible, setIsVisible] = useState(false); useEffect(() => { const target = targetRef.current; if (!target) return; const observer = new IntersectionObserver( ([entry]: IntersectionObserverEntry[]) => { if (entry.isIntersecting) { setIsVisible(true); } }, { threshold: 0.1 } ); observer.observe(target); return () => observer.disconnect(); }, []); return (

{isVisible ? : }

); } ``` Notes: - We read `targetRef.current` inside the effect so we have the node after mount. - The dependency array is `[]` so we set up once and clean up on unmount. If the element were dynamic (e.g. conditional), you'd depend on whatever identifies that element and re-run the effect when it changes. - Cleanup calls `observer.disconnect()` so we don't leave the observer active after unmount. ### Tie-in with refs This pattern is exactly where React refs shine: you need a stable reference to a DOM node for an imperative API (IntersectionObserver), and you must not trigger re-renders just from holding that reference. Refs give you the node and a place to store the observer without affecting the render cycle. For more on refs, see the [React Refs deep dive](/posts/2026/react/react-refs-the-complete-deep-dive). --- ## Custom useIntersectionObserver Hook You can wrap the observer logic in a reusable hook so any component can "observe" an element and get visibility (or the full entry). ### Hook that returns isIntersecting Type the ref as `React.RefObject` and the options as `IntersectionObserverInit`; return a small object so consumers get typed `entry` and `isIntersecting`: ```tsx function useIntersectionObserver( ref: React.RefObject, options: IntersectionObserverInit = {} ): { isIntersecting: boolean; entry: IntersectionObserverEntry | null } { const { threshold = 0, root = null, rootMargin = '0px' } = options; const [isIntersecting, setIsIntersecting] = useState(false); const [entry, setEntry] = useState(null); useEffect(() => { const target = ref?.current; if (!target) return; const observer = new IntersectionObserver( ([entry]: IntersectionObserverEntry[]) => { setEntry(entry); setIsIntersecting(entry.isIntersecting); }, { threshold, root, rootMargin } ); observer.observe(target); return () => observer.disconnect(); }, [ref, threshold, root, rootMargin]); return { isIntersecting, entry }; } ``` Usage: ```tsx function MyComponent() { const ref = useRef(null); const { isIntersecting } = useIntersectionObserver(ref, { threshold: 0.5 }); return (

{isIntersecting ? 'Visible' : 'Not visible'}

); } ``` ### Supporting optional ref Some call sites might pass the ref conditionally. A common pattern is to accept either a ref object or nothing and skip observing when there's no ref: ```tsx function useIntersectionObserver( refOrNull: React.RefObject | null, options: IntersectionObserverInit = {} ): { isIntersecting: boolean; entry: IntersectionObserverEntry | null } { const [state, setState] = useState<{ isIntersecting: boolean; entry: IntersectionObserverEntry | null; }>({ isIntersecting: false, entry: null }); useEffect(() => { const ref = refOrNull; const target = ref?.current; if (!target) return; const observer = new IntersectionObserver( ([entry]: IntersectionObserverEntry[]) => { setState({ isIntersecting: entry.isIntersecting, entry }); }, options ); observer.observe(target); return () => observer.disconnect(); }, [refOrNull, options.threshold, options.root, options.rootMargin]); return state; } ``` Note: dependency on `refOrNull?.current` can be tricky because the ref object is stable but `.current` changes. In practice, many hooks depend on `refOrNull` (the ref object) and run the effect once when the ref is first set; if the same ref is reused for different elements, you might need a different strategy (e.g. key the effect by a stable id). For the common case "one ref, one element," the simple `[]` dependency or `[ref]` is often enough. ### Return only entry (flexible) If you prefer to let the consumer read `entry.isIntersecting` or `entry.intersectionRatio`, you can return just the entry: ```tsx function useIntersectionObserver( ref: React.RefObject, options?: IntersectionObserverInit ): IntersectionObserverEntry | null { const [entry, setEntry] = useState(null); useEffect(() => { const target = ref?.current; if (!target) return; const observer = new IntersectionObserver( ([entry]: IntersectionObserverEntry[]) => setEntry(entry), options ?? {} ); observer.observe(target); return () => observer.disconnect(); }, [ref, options?.threshold, options?.root, options?.rootMargin]); return entry; } ``` Then: `const entry = useIntersectionObserver(ref, {});` and use `entry?.isIntersecting`, `entry?.intersectionRatio`, etc. TypeScript will infer the return type from `IntersectionObserverEntry | null`. --- ## Practical Use Cases ### Lazy load images Load the image `src` only when the element is near or in the viewport: ```tsx type LazyImageProps = React.ComponentProps<'img'> & { src: string; alt: string }; function LazyImage({ src, alt, ...props }: LazyImageProps) { const ref = useRef(null); const [imageSrc, setImageSrc] = useState(null); useEffect(() => { const target = ref.current; if (!target) return; const observer = new IntersectionObserver( ([entry]: IntersectionObserverEntry[]) => { if (entry.isIntersecting) { setImageSrc(src); observer.unobserve(entry.target); } }, { rootMargin: '100px' } ); observer.observe(target); return () => observer.disconnect(); }, [src]); return {alt}

; } ``` You can also use the native `loading="lazy"` attribute for images; the browser does something similar. IntersectionObserver is still useful for custom placeholders, non-img content, or when you need a specific rootMargin/threshold. ### Infinite scroll Place a "sentinel" element at the bottom of the list. When it becomes visible, load more items: ```tsx type Item = { id: string; name: string }; function InfiniteList() { const [items, setItems] = useState([]); const [loading, setLoading] = useState(false); const sentinelRef = useRef(null); useEffect(() => { const sentinel = sentinelRef.current; if (!sentinel) return; const observer = new IntersectionObserver( ([entry]: IntersectionObserverEntry[]) => { if (entry.isIntersecting && !loading) { setLoading(true); fetchMoreItems().then((more: Item[]) => { setItems((prev) => [...prev, ...more]); setLoading(false); }); } }, { root: null, rootMargin: '200px', threshold: 0 } ); observer.observe(sentinel); return () => observer.disconnect(); }, [loading]); return ( <>

{item.name}

{loading &&

Loading more...

} ); } ``` Using `rootMargin: '200px'` triggers loading slightly before the sentinel is on screen for a smoother experience. ### Scroll-triggered animations Add a class or run an animation when a section enters the viewport: ```tsx function AnimatedSection({ children }: { children: React.ReactNode }) { const ref = useRef(null); useEffect(() => { const target = ref.current; if (!target) return; const observer = new IntersectionObserver( ([entry]: IntersectionObserverEntry[]) => { if (entry.isIntersecting) { target.classList.add('animate-in'); } }, { threshold: 0.2 } ); observer.observe(target); return () => observer.disconnect(); }, []); return

{children}

; } ``` CSS can define `.animate-in` (e.g. opacity and transform). For more control, you can use `entry.intersectionRatio` to drive opacity or transform in a requestAnimationFrame loop or with an animation library. ### Sticky header / "back to top" visibility Observe a sentinel above the main content; when it's not intersecting, show a sticky header or a "back to top" button: ```tsx const sentinelRef = useRef(null); const [showHeader, setShowHeader] = useState(false); useEffect(() => { const sentinel = sentinelRef.current; if (!sentinel) return; const observer = new IntersectionObserver( ([entry]: IntersectionObserverEntry[]) => { setShowHeader(!entry.isIntersecting); }, { threshold: 0 } ); observer.observe(sentinel); return () => observer.disconnect(); }, []); ``` Render a hidden sentinel at the top of the page and your sticky header or button based on `showHeader`. ### Read time / visibility analytics Record when a block becomes visible (e.g. for "read" tracking): ```tsx useEffect(() => { const target = ref.current; if (!target) return; const observer = new IntersectionObserver( ([entry]: IntersectionObserverEntry[]) => { if (entry.isIntersecting) { analytics.track('section_viewed', { id: sectionId }); observer.unobserve(entry.target); } }, { threshold: 0.5 } ); observer.observe(target); return () => observer.disconnect(); }, [sectionId]); ``` --- ## Performance and Best Practices ### One observer for many elements You can observe many elements with a single observer. Create one observer and call `observe()` for each target. The callback will receive entries for whichever targets crossed a threshold. This is more efficient than creating one observer per element. ```ts const observer = new IntersectionObserver(callback, options); elements.forEach((el: Element) => observer.observe(el)); // Cleanup: observer.disconnect(); ``` In React, if you have a list of refs (e.g. from a map), you can observe all of them in one effect and disconnect on cleanup. ### Don't observe too many elements Observing hundreds of elements can still be costly. For very long lists, consider observing only a subset (e.g. a sentinel for infinite scroll) or virtualizing the list so only visible items exist in the DOM. ### Use root for scroll containers If your scroll is inside a div (not the window), pass that div as `root`. Otherwise the observer uses the viewport and may not fire as expected when the user scrolls inside the container. ### rootMargin for preloading Use a positive rootMargin so you trigger a bit before the element is visible (e.g. start loading an image 100–200px before it enters the viewport). That reduces perceived delay. ### Optional debouncing Usually you don't need to debounce the callback; the browser already batches. If you're doing heavy work in the callback (e.g. complex state updates or layout), consider throttling or batching that work, but the observer API itself doesn't require debouncing. --- ## Common Pitfalls ### Forgetting cleanup If you don't call `disconnect()` (or `unobserve()`) in the effect cleanup, the observer keeps running and the callback may run after the component has unmounted. That can set state on an unmounted component and cause warnings or leaks. Always clean up: ```ts return () => observer.disconnect(); ``` ### Reading ref before mount In the first render, `ref.current` can be `null` because the element isn't in the DOM yet. So you must create the observer inside `useEffect` (after commit) and guard: `if (!ref.current) return;`. Don't create the observer in render or assume `ref.current` is set during render. ### SSR: no window or IntersectionObserver On the server (e.g. Next.js, Remix), `window` and `IntersectionObserver` may be undefined. Guard before creating the observer: ```ts useEffect(() => { if (typeof IntersectionObserver === 'undefined') return; const target = ref.current; if (!target) return; // ... }, []); ``` Or use a polyfill for older browsers; in SSR you typically skip observing until the client hydrates. ### isIntersecting vs intersectionRatio `isIntersecting` is true whenever `intersectionRatio > 0`. So a single pixel visible makes it true. For "has the user actually seen this?" you might want a higher threshold (e.g. 0.5) in the options and then check `entry.isIntersecting` (which will now reflect that threshold). Also, the callback can fire with `isIntersecting: false` when the element leaves; handle both directions if your logic depends on it. ### Stale closures in the callback If your callback uses state or props (e.g. calling `setItems` or a prop function), make sure you're not closing over stale values. Use refs for the latest callback or list the dependencies in the effect and re-create the observer when they change, depending on what you need. --- ## Summary and Quick Reference ### When to use IntersectionObserver - Lazy loading (images, components) - Infinite scroll (sentinel at bottom) - Scroll-triggered animations or classes - Sticky headers, "back to top" visibility - Analytics (visibility / read tracking) ### Options cheat sheet | Option | Default | Purpose | |--------|---------|---------| | `root` | `null` (viewport) | Scroll container element | | `rootMargin` | `'0px'` | Expand/shrink root (CSS margin syntax) | | `threshold` | `0` | Visibility ratio 0–1 or array of ratios | ### React pattern recap 1. **Ref for target:** `

` 2. **Create observer in useEffect** with `targetRef.current`; guard if null. 3. **Cleanup:** `return () => observer.disconnect();` 4. **Optional:** Reusable `useIntersectionObserver(ref, options)` returning `{ isIntersecting, entry }` or just `entry`. ### Connection to refs IntersectionObserver needs a DOM element to observe. In React, you get that element via a **ref**. The observer itself is also best kept in a ref or inside an effect so you can disconnect on unmount. Refs are the bridge between React's declarative tree and imperative APIs like IntersectionObserver. For a full treatment of refs, see the [React Refs deep dive](/posts/2026/react/react-refs-the-complete-deep-dive). IntersectionObserver is a small, focused API. Once you know the options and the React pattern (ref + useEffect + cleanup), you can use it for lazy loading, infinite scroll, and scroll-driven UI without scroll listeners or layout thrashing.

IntersectionObserver: The Complete Deep Dive