Intersection Observer API: visibility without scroll listeners

Before Intersection Observer, “is this element on screen?” usually meant subscribing to scroll (or resize) and calling geometry APIs such as getBoundingClientRect() on the hot path. That pattern couples your logic to high-frequency input, forces synchronous style and layout work, and is easy to get wrong with nested scroll containers, dynamic layout, transforms, or composited overflow. The W3C Intersection Observer specification was added precisely to retire that pattern.

Intersection Observer inverts the relationship: you register interest, the user agent tracks how a target intersects a root intersection rectangle derived from a root, rootMargin, and scrollMargin, and the browser delivers IntersectionObserverEntry objects when the intersection crosses a configured threshold. The processing model is integrated into the HTML event loop’s Update the rendering step via the spec’s HTML Processing Model: Event Loop section.

This article is a practitioner’s reference: option semantics, callback timing, the entry shape, cross-origin and V2 caveats, sharp edges, cleanup, and the cases where a different API is the better tool. It assumes you know the rendering pipeline at the level of “style → layout → paint → composite” and have used MutationObserver, ResizeObserver, or one of their kin.

Mental model: from scroll math to async notifications

The browser repeatedly answers a single geometry question — “how much of target lies inside the root’s effective clip, possibly inflated by margins?” — and only invokes your callback when the answer crosses a configured threshold or the isIntersecting flag flips. That keeps visibility-driven work out of scroll handlers and lets the user agent batch and coalesce updates with the rest of its rendering work.

Three pieces of state govern every notification:

• The root intersection rectangle — the rectangle the target is intersected against, derived from the explicit root element (its padding area when it has a content clip, otherwise its bounding client rect) or the top-level document’s viewport for the implicit root, then expanded by rootMargin.
• The intersection rectangle — the target’s getBoundingClientRect(), walked up the containing block chain, clipped by every ancestor’s overflow and clip-path, and finally intersected with the root intersection rectangle.
• The threshold index — the index of the first configured threshold strictly greater than the current intersectionRatio (intersectionRect.area / boundingClientRect.area), or the list length when the ratio meets or exceeds the last threshold. A notification fires when this index changes, or when isIntersecting flips while the index stays put.

That last point is subtler than it looks. The default threshold = [0] collapses to two effective states because 0 >= 0 is true: once observed, thresholdIndex is always 1 (length of the list), and changes to it can never themselves drive a notification. Under the default, every notification after the first comes from an isIntersecting transition. Both signals are spec-defined in the update intersection observations algorithm; see also the threshold-transition diagram further down.

Lifecycle: observe, deliver, unobserve

The observer object itself is cheap; the ongoing cost is whatever work you do when notifications arrive. A typical lifecycle registers targets, reacts to entries, then narrows or tears down observation when the DOM or the route changes. Per the spec’s IntersectionObserver lifetime rule, an observer stays alive while either it has script references or it has at least one observation target — calling disconnect() while you still hold a reference does not free it.

Configuration: root, rootMargin, scrollMargin, threshold

These four options define what you are intersecting against and when you want to hear about it. They are passed to the IntersectionObserver() constructor and are immutable for the life of the observer. The spec deliberately attaches them to the constructor — not to observe() — because per-target options would not solve any use case the constructor pattern doesn’t already cover, per the interface design note.

root

• root: null (default) uses the implicit root: the top-level browsing context’s document, with the viewport as the root intersection rectangle. This matches lazy-loading, viewport “in view” analytics, and most one-shot patterns.
• root: element uses an explicit root. The target must be a descendant of the root in the containing block chain. The rectangle is the root’s padding area when the root has a content clip (i.e. CSS overflow clipping its children), otherwise the root’s bounding client rect.

rootMargin

rootMargin grows or shrinks the root intersection rectangle before the intersection is computed. Syntax mirrors the CSS margin shorthand ("200px 0px", "10px 20px 10px 20px"); only px and % units are accepted, and percentages resolve against the width of the undilated rectangle, per the rootMargin definition. A malformed string throws SyntaxError from the constructor, per the initialize-a-new-IntersectionObserver algorithm.

Typical uses:

• Prefetch / lazy media — trigger before the element enters the visible region so network and decode work can overlap scrolling (rootMargin: "300px 0px").
• Tighter or looser “in view” for analytics — treat “almost visible” as visible without rewriting the geometry code.

A large positive rootMargin is not free: more elements stay considered intersecting at once, and notification churn rises with the number of thresholds you have configured.

scrollMargin

scrollMargin was added to the spec to fix a real ergonomics gap with rootMargin. It expands or shrinks the scrollport of every nested scroll container on the path between the target and the intersection root, so a single observer rooted on (say) the viewport can prefetch items that are still off-screen inside an inner carousel or virtualized list. The spec text is in the scrollMargin definition; MDN documents the surface in IntersectionObserver.scrollMargin.

threshold

threshold is a single ratio or a list of ratios in [0.0, 1.0]. The user agent computes intersectionRatio for each target and queues a notification when the threshold index changes (or isIntersecting flips). Out-of-range values throw RangeError from the constructor.

Common shapes:

For degenerate targets (width === 0 or height === 0), the spec defines intersectionRatio as 1 when isIntersecting is true and 0 otherwise — so a zero-area target still produces sensible flags but its ratio carries no useful gradient. Read isIntersecting directly when you only care about overlap, not coverage.

The IntersectionObserverEntry shape

Every callback receives a sequence of entries. Each entry is a snapshot at the moment the spec’s task ran, not a continuous signal. The full IDL lives at the IntersectionObserverEntry interface:

Callback delivery: timing, batching, ordering

The callback receives an array of entries, not one. In a single invocation you may see multiple targets that changed in the same update — and even multiple entries for one target if it crossed several thresholds at once. The plurality is structural, not a quirk.

The spec wires the algorithm into the HTML event loop in §3.4.1: the Run the Update Intersection Observations Steps algorithm executes as a substep of the Update the rendering step, after requestAnimationFrame callbacks and after style + layout. That step queues entries onto the observer’s internal [[QueuedEntries]] slot and, the first time per document per turn, queues a single task on a dedicated IntersectionObserver task source — guarded by the document’s IntersectionObserverTaskQueued flag, which is the spec’s own coalescing mechanism. The actual callback runs when that task is later picked up by the event loop.

Practical implications:

• Callbacks are eventually consistent with scrolling and DOM mutations. They reflect a snapshot from the most recent rendering update, not the current synchronous state of the world. Treat them as a “this changed since last time” signal, not a poll.
• One callback per observer per task. All entries queued during the rendering update are delivered together; [[QueuedEntries]] is drained in one shot. The plural shape of entries is a direct consequence.
• The first observation always fires. The spec initializes previousThresholdIndex = -1 and previousIsIntersecting = false for a freshly observed target, so the very next update queues an entry — even if the target is off-screen. That’s why one-shot lazy loaders work cleanly. The pending initial IntersectionObserver targets rule additionally prevents the user agent from skipping the rendering update before the initial observation has happened.
• takeRecords() drains synchronously. When you need to observe-then-cleanup atomically (route change, server-render serialization, tests), call takeRecords() to pull and clear [[QueuedEntries]] without waiting for the task to fire.
• The callback runs on the main thread, per the [Exposed=Window] IDL on the interface. Defer heavy work (requestIdleCallback, an MessageChannel post, splitting across frames) when you observe many nodes.

Cross-origin iframes and privacy

The implicit root spans the list of descendant browsing contexts of the top-level browsing context, so an observer’s targets can live in nested iframes. In practice you can only observe() an element you can reach via the DOM — same-origin iframes from a parent script, or an iframe’s own document from a script running inside it. When the target is cross-origin-domain with the intersection root (the typical case for a script running inside a third-party iframe whose root is the host viewport), the spec carefully constrains what the entry can carry, per the Privacy and Security section:

• rootMargin and scrollMargin are ignored when the target is cross-origin-domain with the root.
• rootBounds is null in entries for cross-origin-domain targets, hiding the root rectangle from script that doesn’t already have access to the host’s geometry.
• Coordinate systems can differ between boundingClientRect and rootBounds when target and root live in different browsing contexts — pre-compute relative positions in the root’s frame if you need to cross-reference.

In practice this matters whenever you ship a third-party widget (ad, embed, share button) and try to observe its own iframe content from the parent: your rootMargin silently has no effect, and you can’t read rootBounds. Either move the observer into the iframe (where it sees its own document) or design around the constraint.

Intersection Observer V2: trackVisibility

V1 answers “is this rect inside that rect?” — purely a geometry question. It cannot tell you whether the target is actually visible to the user, because nothing in V1 considers occlusion (a sibling element painted on top), opacity, CSS filters, or transforms that flatten a target. That gap matters for ad viewability and clickjacking detection, which is why V2 exists.

The V2 editor’s draft adds two constructor options and one entry field:

• trackVisibility: true — the observer additionally runs an occlusion + effects check before reporting an entry as visible.
• delay: number — minimum milliseconds between observations of the same target. Required when trackVisibility is true; the constructor throws NotAllowedError when delay is missing or < 100. The same delay floor also gates per-target re-observation in the run the update intersection observations algorithm — it is both a constructor guard and a runtime throttle.
• entry.isVisible: boolean — true only when the target passed both the intersection check and the visibility check.

Patterns that hold up in production

Lazy-loaded images or iframes

Observe img/iframe nodes, swap src when isIntersecting is true, then unobserve so completed targets stop being scored on every update.

1const io = new IntersectionObserver(2  (entries, obs) => {3    for (const entry of entries) {4      if (!entry.isIntersecting) continue5      const el = entry.target6      if (el instanceof HTMLImageElement && el.dataset.src) {7        el.src = el.dataset.src8        delete el.dataset.src9      }10      obs.unobserve(el)11    }12  },13  { rootMargin: "300px 0px", threshold: 0 },14)1516for (const img of document.querySelectorAll("img[data-src]")) io.observe(img)

For most plain-<img> lazy loading you should reach for the native loading="lazy" attribute first; the observer pattern earns its keep when you need a rootMargin longer than the browser’s heuristic, or when the resource isn’t an <img>/<iframe>.

Sentinel elements for sticky UI

Place a zero-height sentinel just past the point a sticky header should change state and observe it against the implicit root. Toggling a class when the sentinel leaves the root intersection rectangle avoids reading scroll position directly and pairs naturally with root: null.

1const sentinel = document.querySelector("[data-sticky-sentinel]")2const header = document.querySelector("header")34const io = new IntersectionObserver(5  ([entry]) => header.classList.toggle("is-stuck", !entry.isIntersecting),6  { threshold: 0 },7)8io.observe(sentinel)

Container-scoped infinite scroll

Use a non-null root set to the scrolling list container, a rootMargin at the bottom to prefetch the next page, and a threshold near 0 so you trigger as soon as the sentinel row barely enters the scrollable region.

1const list = document.querySelector("#feed")2const sentinel = document.querySelector("#feed-end")34const io = new IntersectionObserver(5  ([entry]) => {6    if (!entry.isIntersecting) return7    loadNextPage().then((items) => append(list, items))8  },9  { root: list, rootMargin: "0px 0px 800px 0px", threshold: 0 },10)11io.observe(sentinel)

If your list is virtualized inside another scrollable region (modal, side panel), prefer a single observer rooted at the outermost viewport with scrollMargin on the inner container instead of one observer per scroll layer.

Gotchas and failure modes

• Wrong root for the DOM structure. If the root is not the element that actually clips scrolling, intersection state may not change when you visually expect it to. Validate against real markup, especially with portaled UI (dialogs, shadow DOM hosts, popovers) where “what scrolls” is non-obvious.
• Transforms and visual effects. The spec computes intersection from getBoundingClientRect(), which per CSSOM View reflects post-transform layout. Translations, scales, and 3D transforms therefore do affect intersection, but opacity, blur filters, and clip-path on the target do not — V1 sees through them. Use V2 with trackVisibility (where supported) when that gap matters.
• display: none and detached targets. Elements with display: none produce no boxes; targets removed from the document do not generate intersections. Re-observe after they become measurable if you reuse nodes.
• Many thresholds × many targets. Notification cost scales with both. Prefer the smallest threshold list that answers your question, and unobserve aggressively.
• Pinch zoom doesn’t move the rectangle. The spec leaves the root intersection rectangle at the unadjusted viewport size during pinch zoom (it acts like a magnifying glass, per the interface note). Don’t try to derive zoom level from intersection geometry.
• Pairing with scroll listeners. If you also need exact scroll offsets, you usually want scroll + requestAnimationFrame, not Intersection Observer. Layering the two for the same feature often defeats the purpose.

Cleanup

Long-lived SPAs should treat observers like any other subscription:

• unobserve(target) when a component unmounts or a one-shot action completes.
• disconnect() when tearing down a feature that registered many targets.
• takeRecords() before disconnect when you need to react to anything queued but not yet delivered (most common in tests and SSR-hydration paths).

Holding references to large DOM subtrees through observer closures can keep them alive after disconnect() if your callback captures nodes unnecessarily — read from entry.target and avoid closing over component trees. Per the spec’s lifetime rule, the observer itself is collectible only when both script references and observation targets are gone.

When not to use Intersection Observer

Reach for a different tool when you need:

• Per-frame or per-pixel coupling to scroll position — parallax tied to exact offsets, custom scrollbar math, or scroll-linked animation. Use scroll-driven animations (CSS animation-timeline: view() / scroll()) where supported, or scroll + requestAnimationFrame otherwise.
• Synchronous layout-dependent reads during user input where you cannot tolerate a task delay; use getBoundingClientRect() directly inside the input handler and accept the layout cost.
• Hit testing semantics unrelated to a root rectangle — pointer paths, drag-and-drop hover targets — where elementFromPoint or event geometry is clearer.
• Skipping render of off-screen content as a CSS concern — content-visibility: auto lets the user agent skip layout/paint of off-screen subtrees declaratively, which is often what people reach for Intersection Observer to do imperatively.

Intersection Observer is optimized for coarse, transition-based visibility signals; it is not a general replacement for the scroll event, nor a measurement primitive.

Further reading

• W3C Intersection Observer specification — the normative source; integration with the HTML event loop is in §3.4.
• W3C Intersection Observer V2 editor’s draft — trackVisibility, delay, isVisible.
• MDN — Intersection Observer API — readable reference; the scrollMargin page also has live examples.
• web.dev — Trust is good, observation is better: Intersection Observer V2 — Chrome team’s V2 walkthrough with the click-fraud motivation.
• CSS Containment Module Level 2 — content-visibility — declarative alternative for skipping off-screen layout/paint.
• W3C Intersection Observer GitHub repository — historical issues, the (pre-Baseline) reference polyfill, and active spec discussion.