Intersection Observer

1. Introduction

The web’s traditional position calculation mechanisms rely on explicit queries of DOM state that are known to cause (expensive) style recalculation and layout and, frequently, are a source of significant performance overhead due to continuous polling for this information.

A body of common practice has evolved that relies on these behaviors, however, including (but not limited to):

• Building custom pre- and deferred-loading of DOM and data.

• Implementing data-bound high-performance scrolling lists which load and render subsets of data sets. These lists are a central mobile interaction idiom.

• Calculating element visibility. In particular, ad networks now require reporting of ad "visibility" for monetizing impressions. This has led to many sites abusing scroll handlers (causing jank on scroll), synchronous layout invoking readbacks (causing unnecessary critical work in rAF loops), and resorting to exotic plugin-based solutions for computing "true" element visibility (with all the associated overhead of the plugin architecture).

These use-cases have several common properties:

1. They can be represented as passive "queries" about the state of individual elements with respect to some other element (or the global viewport).

2. They do not impose hard latency requirements; that is to say, the information can be delivered asynchronously (e.g. from another thread) without penalty.

3. They are poorly supported by nearly all combinations of existing web platform features, requiring extraordinary developer effort despite their widespread use.

A notable non-goal is pixel-accurate information about what was actually displayed (which can be quite difficult to obtain efficiently in certain browser architectures in the face of filters, webgl, and other features). In all of these scenarios the information is useful even when delivered at a slight delay and without perfect compositing-result data.

The Intersection Observer API addresses the above issues by giving developers a new method to asynchronously query the position of an element with respect to other elements or the global viewport. The asynchronous delivery eliminates the need for costly DOM and style queries, continuous polling, and use of custom plugins. By removing the need for these methods it allows applications to significantly reduce their CPU, GPU and energy costs.

var observer = new IntersectionObserver(changes => {
  for (const change of changes) {
    console.log(change.time);               // Timestamp when the change occurred
    console.log(change.rootBounds);         // Unclipped area of root
    console.log(change.boundingClientRect); // target.boundingClientRect()
    console.log(change.intersectionRect);   // boundingClientRect, clipped by its containing block ancestors, and intersected with rootBounds
    console.log(change.intersectionRatio);  // Ratio of intersectionRect area to boundingClientRect area
    console.log(change.target);             // the Element target
  }
}, {});
// Watch for intersection events on a specific target Element.
observer.observe(target);
// Stop watching for intersection events on a specific target Element.
observer.unobserve(target);
// Stop observing threshold events on all target elements.
observer.disconnect();

2. Intersection Observer

The Intersection Observer API enables developers to understand the visibility and position of target DOM elements relative to an intersection root.

2.1. The IntersectionObserverCallback

callback IntersectionObserverCallback = void (sequence<IntersectionObserverEntry> entries, IntersectionObserver observer);

This callback will be invoked when there are changes to target’s intersection with the intersection root, as per the processing model.

2.2. The IntersectionObserver interface

The IntersectionObserver interface can be used to observe changes in the intersection of an intersection root and one or more target Elements.

An IntersectionObserver with a root Element can observe any target Element that is a descendant of the root in the containing block chain.

An IntersectionObserver with no root Element will automatically observe intersections with the implicit root, and valid targets include any Element in the top-level browsing context, as well as any Element in any nested browsing contexts inside the top-level browsing context.

Note: In MutationObserver, the MutationObserverInit options are passed to observe() while in IntersectionObserver they are passed to the constructor. This is because for MutationObserver, each Node being observed could have a different set of attributes to filter for. For IntersectionObserver, developers may choose to use a single observer to track multiple targets using the same set of options; or they may use a different observer for each tracked target.

rootMargin or threshold values for each target seems to introduce more complexity without solving additional use-cases. Per-observe() options could be provided in the future if V2 introduces a need for it.

[Constructor(IntersectionObserverCallback callback, optional IntersectionObserverInit options),
 Exposed=Window]
interface IntersectionObserver {
  readonly attribute Element? root;
  readonly attribute DOMString rootMargin;
  readonly attribute FrozenArray<double> thresholds;
  void observe(Element target);
  void unobserve(Element target);
  void disconnect();
  sequence<IntersectionObserverEntry> takeRecords();
};

The intersection root for an IntersectionObserver is the value of its root attribute, or else the top-level browsing context’s document node (referred to as the implicit root) if the root attribute is null.

The root intersection rectangle for an IntersectionObserver is the rectangle we’ll use to check against the targets.

If the intersection root is the implicit root,

it’s the viewport’s size.

If the intersection root has an overflow clip,

it’s the element’s content area.

Otherwise,

it’s the result of running the getBoundingClientRect() algorithm on the intersection root.

For any target which belongs to the same unit of related similar-origin browsing contexts as the intersection root, the rectangle is then expanded according to the offsets in the IntersectionObserver’s [[rootMargin]] slot in a manner similar to CSS’s margin property, with the four values indicating the amount the top, right, bottom, and left edges, respectively, are offset by, with positive lengths indicating an outward offset. Percentages are resolved relative to the width of the undilated rectangle.

Note: rootMargin only applies to the intersection root itself. If a target Element is clipped by an ancestor other than the intersection root, that clipping is unaffected by rootMargin.

Note: Root intersection rectangle is not affected by pinch zoom and will report the unadjusted viewport, consistent with the intent of pinch zooming (to act like a magnifying glass and NOT change layout.)

To parse a root margin from an input string marginString, returning either a list of 4 pixel lengths or percentages, or failure:

1. Parse a list of component values marginString, storing the result as tokens.

2. Remove all whitespace tokens from tokens.

3. If the length of tokens is 0 or greater than 4, return failure.

4. Replace each token in tokens:

   • If token is an absolute length dimension token, replace it with a an equivalent pixel length.

   • If token is a <percentage> token, replace it with an equivalent percentage.

   • Otherwise, return failure.

5. If there is one element in tokens, append three duplicates of that element to tokens. If there is two elements are tokens, append a duplicate of each element to tokens. If there are three elements in tokens, append a duplicate of the second element to tokens.

6. Return tokens.

2.3. The IntersectionObserverEntry interface

[Constructor(IntersectionObserverEntryInit intersectionObserverEntryInit)]
interface IntersectionObserverEntry {
  readonly attribute DOMHighResTimeStamp time;
  readonly attribute DOMRectReadOnly? rootBounds;
  readonly attribute DOMRectReadOnly boundingClientRect;
  readonly attribute DOMRectReadOnly intersectionRect;
  readonly attribute boolean isIntersecting;
  readonly attribute double intersectionRatio;
  readonly attribute Element target;
};
dictionary IntersectionObserverEntryInit {
  required DOMHighResTimeStamp time;
  required DOMRectInit? rootBounds;
  required DOMRectInit boundingClientRect;
  required DOMRectInit intersectionRect;
  required boolean isIntersecting;
  required double intersectionRatio;
  required Element target;
};

2.4. The IntersectionObserverInit dictionary

dictionary IntersectionObserverInit {
  Element?  root = null;
  DOMString rootMargin = "0px";
  (double or sequence<double>) threshold = 0;
};

3. Processing Model

This section outlines the steps the user agent must take when implementing the Intersection Observer API.

3.1. Internal Slot Definitions

3.1.1. Document

Each Document has an IntersectionObserverTaskQueued flag which is initialized to false.

3.1.2. Element

Element objects have an internal [[RegisteredIntersectionObservers]] slot, which is initialized to an empty list. This list holds IntersectionObserverRegistration records, which have an observer property holding an IntersectionObserver, a previousThresholdIndex property holding a number between -1 and the length of the observer’s thresholds property (inclusive), and a previousIsIntersecting property holding a boolean.

3.1.3. IntersectionObserver

IntersectionObserver objects have internal [[QueuedEntries]] and [[ObservationTargets]] slots, which are initialized to empty lists and an internal [[callback]] slot which is initialized by IntersectionObserver(callback, options). They also have an internal [[rootMargin]] slot which is a list of four pixel lengths or percentages.

3.2. Algorithms

3.2.1. Queue an Intersection Observer Task

To queue an intersection observer task for a Document document, run these steps:

1. If document’s IntersectionObserverTaskQueued flag is set to true, return.

2. Set document’s IntersectionObserverTaskQueued flag to true.

3. Queue a task to the document’s event loop to notify intersection observers.

3.2.2. Notify Intersection Observers

To notify intersection observers for a Document document, run these steps:

1. Set document’s IntersectionObserverTaskQueued flag to false.

2. Let notify list be a list of all IntersectionObservers whose root is in the DOM tree of document.

3. For each IntersectionObserver object observer in notify list, run these steps:

   1. If observer’s internal [[QueuedEntries]] slot is empty, continue.

   2. Let queue be a copy of observer’s internal [[QueuedEntries]] slot.

   3. Clear observer’s internal [[QueuedEntries]] slot.

   4. Invoke callback with queue as the first argument and observer as the second argument and callback this value. If this throws an exception, report the exception.

3.2.3. Queue an IntersectionObserverEntry

To queue an IntersectionObserverEntry for an IntersectionObserver observer, given a Document document; DOMHighResTimeStamp time; DOMRects rootBounds, boundingClientRect, intersectionRect, and isIntersecting flag; and an Element target; run these steps:

1. Construct an IntersectionObserverEntry, passing in time, rootBounds, boundingClientRect, intersectionRect, isIntersecting, and target.

2. Append it to observer’s internal [[QueuedEntries]] slot.

3. Queue an intersection observer task for document.

3.2.4. Compute the Intersection of a Target Element and the Root

To compute the intersection between a target and the observer’s intersection root, run these steps:

1. Let intersectionRect be the result of running the getBoundingClientRect() algorithm on the target.

2. Let container be the containing block of the target.

3. While container is not the intersection root:

   1. Map intersectionRect to the coordinate space of container.

   2. If container has overflow clipping or a css clip-path property, update intersectionRect by applying container’s clip.

   3. If container is the root element of a nested browsing context, update container to be the browsing context container of container, and update intersectionRect by clipping to the viewport of the nested browsing context. Otherwise, update container to be the containing block of container.

4. Map intersectionRect to the coordinate space of the intersection root.

5. Update intersectionRect by intersecting it with the root intersection rectangle.

6. Map intersectionRect to the coordinate space of the viewport of the Document containing the target.

3.2.5. Run the Update Intersection Observations Steps

To run the update intersection observations steps for a Document document given a timestamp time, run these steps:

1. Let observer list be a list of all IntersectionObservers whose root is in the DOM tree of document.

2. For each observer in observer list:

   1. Let rootBounds be observer’s root intersection rectangle.

   2. For each target in observer’s internal [[ObservationTargets]] slot, processed in the same order that observe() was called on each target:

      1. If the intersection root is not the implicit root and target is not a descendant of the intersection root in the containing block chain, skip further processing for target.

      2. If the intersection root is not the implicit root, and target is not in the same Document as the intersection root, skip further processing for target.

      3. Let targetRect be a DOMRectReadOnly obtained by running the getBoundingClientRect() algorithm on target.

      4. Let intersectionRect be the result of running the compute the intersection algorithm on target.

      5. Let targetArea be targetRect’s area.

      6. Let intersectionArea be intersectionRect’s area.

      7. Let isIntersecting be true if targetRect and rootBounds intersect or are edge-adjacent, even if the intersection has zero area (because rootBounds or targetRect have zero area); otherwise, let isIntersecting be false.

      8. If targetArea is non-zero, let intersectionRatio be intersectionArea divided by targetArea.
         Otherwise, let intersectionRatio be 1 if isIntersecting is true, or 0 if isIntersecting is false.

      9. Let thresholdIndex be the index of the first entry in observer.thresholds whose value is greater than intersectionRatio, or the length of observer.thresholds if intersectionRatio is greater than or equal to the last entry in observer.thresholds.

      10. Let intersectionObserverRegistration be the IntersectionObserverRegistration record in target’s internal [[RegisteredIntersectionObservers]] slot whose observer property is equal to observer.

      11. Let previousThresholdIndex be the intersectionObserverRegistration’s previousThresholdIndex property.

      12. Let previousIsIntersecting be the intersectionObserverRegistration’s previousIsIntersecting property.

      13. If thresholdIndex does not equal previousThresholdIndex or if isIntersecting does not equal previousIsIntersecting, queue an IntersectionObserverEntry, passing in observer, time, rootBounds, boundingClientRect, intersectionRect, isIntersecting, and target.

      14. Assign threshold to intersectionObserverRegistration’s previousThresholdIndex property.

      15. Assign isIntersecting to intersectionObserverRegistration’s previousIsIntersecting property.

3.3. IntersectionObserver Lifetime

An IntersectionObserver will remain alive until both of these conditions hold:

• There are no scripting references to the observer.
• The observer is not observing any targets.

An IntersectionObserver will continue observing a target until either unobserve(target) is called on the target, or disconnect() is called on the observer.

3.4. External Spec Integrations

3.4.1. HTML Processing Model: Event Loop

An Intersection Observer processing step should take place during the "Update the rendering" steps, after step 9, run the fullscreen rendering steps, and before step 10, run the animation frame callbacks, in the in the HTML Processing Model.

This step is:

10. For each fully active Document in docs, Run the update intersection observations steps for each IntersectionObserver whose root is in the DOMtree of that Document.

4. Acknowledgements

Special thanks to all the contributors for their technical input and suggestions that led to improvements to this specification.