JavaScript Reference ยท DOM: Document and Elements
The IntersectionObserver interface
Reference for IntersectionObserver: root, rootMargin and threshold options, IntersectionObserverEntry fields, lazy loading, infinite scroll and cleanup.
An IntersectionObserver tells you when an element enters or leaves the visible area of the viewport, or of a scrolling container you choose. It reports how much of the element overlaps that area, without you having to listen to scroll events or measure rectangles on every frame.
Typical uses are lazy loading images, starting animations when something scrolls in, loading more items at the end of a list and tracking which section the reader is on.
const observer = new IntersectionObserver((entries) => { for (const entry of entries) { console.log(entry.target.id, entry.isIntersecting); } }, { threshold: 0.5 }); observer.observe(element);
Try it
Syntax
const observer = new IntersectionObserver(callback, options); observer.observe(target); observer.unobserve(target); observer.disconnect(); const entries = observer.takeRecords();
Parameters
| Name | Description |
|---|---|
callback(entries, observer) |
Called with an array of IntersectionObserverEntry objects, one per target whose state crossed a threshold. |
options.root |
The scrolling element to measure against. null or omitted means the browser viewport. |
options.rootMargin |
CSS-like margin string such as "100px 0px" that grows or shrinks the root before measuring. Default "0px". |
options.threshold |
A number or array of numbers between 0 and 1: visible fractions at which to call back. Default 0. |
Entry fields
target, isIntersecting, intersectionRatio, intersectionRect, boundingClientRect, rootBounds and time.
Return value and exceptions
observe(), unobserve() and disconnect() return undefined; takeRecords() returns pending entries. The constructor throws a RangeError for thresholds outside 0 to 1 and a SyntaxError for a malformed rootMargin.
Usage notes
- An initial callback always arrives. After
observe(), the browser reports the starting state of the target once, even when it is not visible (isIntersecting: false). CheckisIntersectingbefore acting. - Thresholds trigger on crossings. With
threshold: 0.5you get a call when the visible fraction passes 0.5 in either direction, not continuously while scrolling. - Pre-load with
rootMargin. A positive margin such as"200px"fires before an element is actually on screen, which suits lazy loading and infinite scroll sentinels. - Tall targets and thresholds. An element taller than the viewport can never be 100% visible; use a low threshold or an array such as
[0, 0.25, 0.5, 0.75, 1]. - Stop observing when done. For one-time reveals call
unobserve(entry.target); calldisconnect()for everything. rootmust be an ancestor of the targets. Clipping byoverflow: hiddenancestors counts toward visibility.- Entries are asynchronous. They are queued and delivered at idle-friendly times, so do not use this API for pixel-perfect scroll effects; CSS scroll-driven animations or
requestAnimationFramefit those better. - Hidden targets (
display: none) never intersect. - For images, the HTML
loading="lazy"attribute covers the most common case without any JavaScript.
Browser support
IntersectionObserver is supported in all current browsers. Newer additions, such as the trackVisibility and delay options, are not universal, so check a compatibility table.