Intersection Observer API

The Intersection Observer API provides a way to asynchronously observe changes in the intersection of a target element with an ancestor element or with a top-level document's viewport.

Intersection observer concepts and usage

The Intersection Observer API allows you to configure a callback that is called whenever one item, called a target, intersects either the device viewport or a specified element called, for the purpose of this API, the root element. Create the intersection observer by calling its constructor and passing it a reference to the callback function.

var options = {
    root: document.querySelector('#scrollArea'),
    rootMargin: '0px',
    threshold: 1.0
}
var callback = function(entries, observer) { 
    /* Content excerpted, show below */ 
};
var observer = new IntersectionObserver(callback, options);

A threshold of 1.0 means that when 100 percent of target is visible within the root element, the callback is invoked.

options

root

The element that is used as the viewport for checking visiblity of the target. Defaults to the browser viewport.

rootMargin

Margin around the root. Can have values similar to the css margin property: "10px 20px 30px 40px" (top, right, bottom, left). If the root element is specified % values can be used.

threshold

Number or array of numbers to indicate at what % of visiblity of the target the observer should trigger. eg: trigger for every 25 percent that comes into view: [0, 0.25, 0.5, 0.75, 1]

Once you have the observer, give it a target.

var target = document.querySelector('#listItem');
observer.observe(target);

Whenever the target meets the threshold specified for the IntersectionObserver, the callback is invoked.

var callback = function(entries, observer) { 
    entries.forEach(entry => {
        entry.time;               // a DOMHightResTimeStamp indicating when the intersection occurred.
        entry.rootBounds;         // a DOMRectReadOnly for the intersection observer's root.
        entry.boundingClientRect; // a DOMRectReadOnly for the intersection observer's target.
        entry.intersectionRect;   // a DOMRectReadOnly for the visible portion of the intersection observer's target.
        entry.intersectionRatio;  // the number for the ratio of the intersectionRect to the boundingClientRect.
        entry.target;             // the Element whose intersection with the intersection root changed.
    });
};

Interfaces

IntersectionObserver

Provides a way to asynchronously observe changes in the intersection of a target element with an ancestor element or with a top-level document's viewport. The ancestor or viewport is referred to as the root.

IntersectionObserverEntry

Provides information about the intersection of a particular target with the observers root element at a particular time. Instances of this interface cannot be created, but a list of them is returned by IntersectionObserver.takeRecords().

Specifications

Specification	Status	Comment
Intersection Observer	Editor's Draft	Initial definition.

Browser compatibility

[1] This feature is available since the Windows Insider Preview Build 14986.

[2] This feature is implemented since Gecko 53.0 (Firefox 53.0 / Thunderbird 53.0 / SeaMonkey 2.50) behind the preference dom.IntersectionObserver.enabled, defaulting to false. See bug 1243846.

See also

• Intersection Observer polyfill