IntersectionObserver answers a geometry question asynchronously
IntersectionObserver tells you when a target intersects a root rectangle. It is built for lazy loading, infinite scrolling, ad visibility, analytics, and scroll-linked activation without running a scroll handler on every frame. The key is that it is asynchronous: the browser computes intersections during its rendering pipeline and delivers entries later.
graph TD Root["root viewport or scroll container"] --> RootMargin["apply rootMargin"] Target["target border box"] --> Clip["clip through ancestors"] RootMargin --> Intersect["intersection rectangle"] Clip --> Intersect Intersect --> Ratio["intersectionRatio thresholds"] Ratio --> Callback["queued observer callback"]
This is why it scales better than manually calling getBoundingClientRect() in scroll events. The engine already has layout and clipping information; the observer lets it batch work.
The geometry model
The observer has three important inputs: root, rootMargin, and threshold.
root is either the viewport or a scrollable ancestor. rootMargin expands or shrinks the root rectangle before intersection is calculated. Positive margins are useful for preloading before an item appears. threshold is one number or an array of ratios where callbacks should fire.
const observer = new IntersectionObserver(onEntries, {
root: document.querySelector(".feed"),
rootMargin: "600px 0px",
threshold: [0, 0.25, 0.5, 1]
});
The target’s visible rectangle is clipped by overflow and ancestor boundaries. Transforms, nested scrolling containers, iframes, and sticky positioning can make the result differ from intuition. The observer reports rectangles; it does not answer whether a user can meaningfully see or understand the element.
Threshold cost and semantics
Thresholds are ratios of intersected area to target area. A threshold of 0.5 means “notify when the visible area crosses 50%.” Large threshold arrays are not free. An array with 101 values for progress tracking creates much more callback churn than [0, 1].
For lazy images, use threshold: 0 and a positive rootMargin. For impression analytics, use a threshold that matches the business definition, such as 0.5, then combine it with a timer. For scroll progress animation, IntersectionObserver is often the wrong primitive; use CSS scroll-driven animations where available or a carefully throttled scroll pipeline.
The callback is not a real-time scroll event. Entries are delivered after the browser has computed layout and intersection state, and multiple threshold crossings can be coalesced. That is exactly what makes the API efficient, but it also means it should not drive effects that require per-pixel precision. Treat it as a state transition signal: became near enough to load, became visible enough to start a timer, reached the sentinel, left the viewport.
isIntersecting and intersectionRatio answer slightly different questions. isIntersecting tells you whether the target intersects the root at all. The ratio tells you how much of the target’s area is intersecting. Very tall elements can have low ratios even when the user sees a meaningful portion, while tiny elements can hit high ratios too easily. For analytics, define visibility in product terms: for example, 50% of an ad for one continuous second, or any part of a heading entering the viewport for table-of-contents activation.
Observer lifecycle
Use a small number of observers with shared options. Creating one observer per item is usually unnecessary; one observer can watch many targets. The browser can batch geometry work across those targets, and your code has one callback path to reason about. Keep a map from element to item id or metadata when the callback needs application context.
Clean up aggressively. Unobserve images after their real source is assigned. Unobserve impression targets after the impression has been counted. Disconnect observers when a route or component tree is destroyed. The observer holds references to targets, so sloppy lifecycle code can retain DOM nodes and application metadata longer than expected.
For list rendering, be careful with recycled DOM nodes. Virtualizers often reuse the same element for different items. If your observer callback closes over an old item id, it can count the wrong impression after recycling. Store the current id on the element or in a weak map updated during render, and validate it when the entry arrives.
Practical patterns
For lazy loading, observe placeholders and unobserve after loading:
const io = new IntersectionObserver((entries) => {
for (const entry of entries) {
if (!entry.isIntersecting) continue;
const img = entry.target;
img.src = img.dataset.src;
io.unobserve(img);
}
}, { rootMargin: "500px 0px", threshold: 0 });
For infinite scroll, observe a sentinel near the end of the list rather than every row. When the sentinel intersects, fetch the next page, append items, and keep the sentinel last.
For virtualized lists, be careful. IntersectionObserver can help detect range edges, but virtualization still needs a deterministic layout model. If item heights are unknown, combine it with ResizeObserver or explicit measurement, and expect more complexity.
For prefetching, prefer a generous rootMargin and idempotent work. A link card entering within 800 px of the viewport might warm route data or image metadata, but the prefetch should be abortable or deduped. Scrolling quickly through a long list can otherwise start dozens of requests the user will never need. Use a queue, concurrency limit, and cache key so “near viewport” is a hint, not an uncontrolled fan-out.
For section navigation, observe headings with thresholds near zero and update the active section based on position and scroll direction, not just the last callback. Multiple headings can intersect at once in a tall viewport. A deterministic tie-breaker such as “nearest heading above the top inset” avoids flickering table-of-contents state.
Failure modes
Wrong root is the most common bug. If content scrolls inside a div but the observer uses the viewport root, entries will not match the user’s scroll. Set root to the scroll container.
Zero-area targets never produce useful ratios. Ensure placeholders have stable dimensions before images load.
Layout shifts cause duplicate impressions. If an element crosses a threshold, shifts away, then crosses again, your analytics may double count. Track impression state per item and require dwell time.
Hidden ancestors can confuse expectations. display: none removes layout boxes; visibility: hidden keeps geometry but not true visibility. IntersectionObserver is geometric, not semantic.
Cross-origin iframes are constrained for privacy. You cannot freely inspect geometry across origins.
Diagnostics
Log entry.boundingClientRect, entry.rootBounds, entry.intersectionRect, entry.intersectionRatio, and entry.time for confusing cases. Draw temporary overlays for root and target rectangles when debugging nested scrollers. In DevTools, inspect computed overflow on ancestors; an unexpected overflow: hidden changes clipping.
When callbacks fire too often, check threshold arrays and layout instability. When callbacks do not fire, check target dimensions, root containment, and whether the target is actually a descendant of the root.
Checklist
- Use the real scroll container as
root. - Give lazy targets stable width and height.
- Prefer
rootMarginover many thresholds for preload distance. - Unobserve one-shot targets after work completes.
- Deduplicate analytics by item and dwell time.
- Do not use it for pixel-perfect scroll animation.
IntersectionObserver is a rendering-pipeline subscription to clipped geometry. It works best when the question is coarse: “near enough to load,” “visible enough to count,” or “at the edge of the list.”