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.getBoundingClientRect()
    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 = undefined (sequence<IntersectionObserverEntry> entries, IntersectionObserver observer);

This callback will be invoked when there are changes to a 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.

The intersection root for an IntersectionObserver is the value of its root attribute if the attribute is non-null; otherwise, it is the top-level browsing context’s document node, referred to as the implicit root.

An IntersectionObserver with a non-null root is referred to as an explicit root observer, and it can observe any target Element that is a descendant of the root in the containing block chain. An IntersectionObserver with a null root is referred to as an implicit root observer. Valid targets for an implicit root observer include any Element in the top-level browsing context, as well as any Element in any nested browsing context which is in the list of the descendant browsing contexts of the top-level browsing context.

When dealing with implicit root observers, the API makes a distinction between a target whose relevant settings object’s origin is same origin-domain with the top-level origin, referred to as a same-origin-domain target; as opposed to a cross-origin-domain target. Any target of an explicit root observer is also a same-origin-domain target, since the target must be in the same document as the intersection root.

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 the need arises.

[Exposed=Window]
interface IntersectionObserver {
  constructor(IntersectionObserverCallback callback, optional IntersectionObserverInit options = {});
  readonly attribute (Element or Document)? root;
  readonly attribute DOMString rootMargin;
  readonly attribute DOMString scrollMargin;
  readonly attribute FrozenArray<double> thresholds;
  readonly attribute long delay;
  readonly attribute boolean trackVisibility;
  undefined observe(Element target);
  undefined unobserve(Element target);
  undefined disconnect();
  sequence<IntersectionObserverEntry> takeRecords();
};

An Element is defined as having a content clip if its computed style has overflow properties that cause its content to be clipped to the element’s padding edge.

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

If the IntersectionObserver is an implicit root observer,

it’s treated as if the root were the top-level browsing context’s document, according to the following rule for document.

If the intersection root is a document,

it’s the size of the document's viewport (note that this processing step can only be reached if the document is fully active).

Otherwise, if the intersection root has a content clip,

it’s the element’s padding area.

Otherwise,

it’s the result of getting the bounding box for the intersection root.

When calculating the root intersection rectangle for a same-origin-domain target, 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.

To apply scroll margin to a scrollport

When calculating a scrollport intersection rectangle for a same-origin-domain target, the rectangle is expanded according to the offsets in the IntersectionObserver’s [[scrollMargin]] 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.

These offsets are only applied when handling same-origin-domain targets; for cross-origin-domain targets they are ignored.

Note: scrollMargin affects the clipping of target by all scrollable ancestors up to and including the intersection root. Both the scrollMargin and the rootMargin are applied to a scrollable intersection root’s rectangle.

Note: Root intersection rectangle and scrollport intersection rectangles are 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 margin (root or scroll) 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 greater than 4, return failure.

4. If there are zero elements in tokens, set tokens to ["0px"].

5. 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.

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

7. Return tokens.

2.3. The IntersectionObserverEntry interface

[Exposed=Window]
interface IntersectionObserverEntry {
  constructor(IntersectionObserverEntryInit intersectionObserverEntryInit);
  readonly attribute DOMHighResTimeStamp time;
  readonly attribute DOMRectReadOnly? rootBounds;
  readonly attribute DOMRectReadOnly boundingClientRect;
  readonly attribute DOMRectReadOnly intersectionRect;
  readonly attribute boolean isIntersecting;
  readonly attribute boolean isVisible;
  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 boolean isVisible;
  required double intersectionRatio;
  required Element target;
};

2.4. The IntersectionObserverInit dictionary

dictionary IntersectionObserverInit {
  (Element or Document)?  root = null;
  DOMString rootMargin = "0px";
  DOMString scrollMargin = "0px";
  (double or sequence<double>) threshold = 0;
  long delay = 0;
  boolean trackVisibility = false;
};

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).

• a previousIsIntersecting property holding a boolean.

• a lastUpdateTime property holding a DOMHighResTimeStamp value.

• a previousIsVisible property holding a boolean.

3.1.3. IntersectionObserver

IntersectionObserver objects have the following internal slots:

• A [[QueuedEntries]] slot initialized to an empty list.

• A [[ObservationTargets]] slot initialized to an empty list.

• A [[callback]] slot which is initialized by IntersectionObserver(callback, options).

• A [[rootMargin]] slot which is a list of four pixel lengths or percentages.

• A [[scrollMargin]] slot which is a list of four pixel lengths or percentages.

• A [[thresholds]] slot which is initialized by IntersectionObserver(callback, options).

• A [[delay]] slot which is initialized by IntersectionObserver(callback, options).

• A [[trackVisibility]] slot which is initialized by IntersectionObserver(callback, options).

3.2. Algorithms

3.2.1. Initialize a new IntersectionObserver

To initialize a new IntersectionObserver, given an IntersectionObserverCallback callback and an IntersectionObserverInit dictionary options, run these steps:

1. Let this be a new IntersectionObserver object

2. Set this’s internal [[callback]] slot to callback.

3. Attempt to parse a margin from options.rootMargin. If a list is returned, set this’s internal [[rootMargin]] slot to that. Otherwise, throw a SyntaxError exception.

4. Attempt to parse a margin from options.scrollMargin. If a list is returned, set this’s internal [[scrollMargin]] slot to that. Otherwise, throw a SyntaxError exception.

5. Let thresholds be a list equal to options.threshold.

6. If any value in thresholds is less than 0.0 or greater than 1.0, throw a RangeError exception.

7. Sort thresholds in ascending order.

8. If thresholds is empty, append 0 to thresholds.

9. The thresholds attribute getter will return this sorted thresholds list.

10. Let delay be the value of options.delay.

11. If options.trackVisibility is true and delay is less than 100, set delay to 100.

12. Set this’s internal [[delay]] slot to options.delay to delay.

13. Set this’s internal [[trackVisibility]] slot to options.trackVisibility.

14. Return this.

3.2.2. Observe a target Element

To observe a target Element, given an IntersectionObserver observer and an Element target, follow these steps:

1. If target is in observer’s internal [[ObservationTargets]] slot, return.

2. Let intersectionObserverRegistration be an IntersectionObserverRegistration record with an observer property set to observer, a previousThresholdIndex property set to -1, a previousIsIntersecting property set to false, and a previousIsVisible property set to false.

3. Append intersectionObserverRegistration to target’s internal [[RegisteredIntersectionObservers]] slot.

4. Add target to observer’s internal [[ObservationTargets]] slot.

3.2.3. Unobserve a target Element

To unobserve a target Element, given an IntersectionObserver observer and an Element target, follow these steps:

1. Remove the IntersectionObserverRegistration record whose observer property is equal to this from target’s internal [[RegisteredIntersectionObservers]] slot, if present.

2. Remove target from this’s internal [[ObservationTargets]] slot, if present

3.2.4. Queue an Intersection Observer Task

The IntersectionObserver task source is a task source used for scheduling tasks to § 3.2.5 Notify Intersection Observers.

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 on the IntersectionObserver task source associated with the document's event loop to notify intersection observers.

3.2.5. 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. Let callback be the value of observer’s internal [[callback]] slot.

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

3.2.6. 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.7. Compute the Intersection of a Target Element and the Root

To compute the intersection between a target target and an intersection root root, run these steps:

1. Let intersectionRect be the result of getting the bounding box for target.

2. Let container be the containing block of target.

3. While container is not root:

   1. If container is the document of a nested browsing context, update intersectionRect by clipping to the viewport of the document, and update container to be the browsing context container of container.

   2. Map intersectionRect to the coordinate space of container.

   3. If container is a scroll container, apply the IntersectionObserver’s [[scrollMargin]] to the container’s clip rect as described in apply scroll margin to a scrollport.

   4. If container has a content clip or a css clip-path property, update intersectionRect by applying container’s clip.

   5. If container is the root element of a browsing context, update container to be the browsing context’s document; otherwise, update container to be the containing block of container.

4. Map intersectionRect to the coordinate space of 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 target.

7. Return intersectionRect.

3.2.8. Compute whether a Target is unoccluded, untransformed, unfiltered, and opaque.

To compute the visibility of a target, run these steps:

1. If the observer’s trackVisibility attribute is false, return false.

2. If the target has an effective transformation matrix other than a 2D translation or proportional 2D upscaling, return false.

3. If the target, or any element in its containing block chain, has an effective opacity other than 100%, return false.

4. If the target, or any element in its containing block chain, has any filters applied, return false.

5. If the implementation cannot guarantee that the target is completely unoccluded by other page content, return false.

Note: Implementations should use the ink overflow rectangle of page content when determining whether a target is occluded. For blur effects, which have theoretically infinite extent, the ink overflow rectangle is defined by the finite-area approximation described for the blur filter function.

6. Return true.

3.2.9. Calculate a target’s Effective Transformation Matrix

1. Let matrix be the serialization of the identity transform function.

2. Let container be the target.

3. While container is not the intersection root:

   1. Set t to container’s transformation matrix.

   2. Set matrix to t post-multiplied by matrix.

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

4. Return matrix.

3.2.10. 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. For the top-level browsing context, this includes implicit root observers.

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. Let registration be the IntersectionObserverRegistration record in target’s internal [[RegisteredIntersectionObservers]] slot whose observer property is equal to observer.

      2. If (time - registration.lastUpdateTime < observer.delay), skip further processing for target.

      3. Set registration.lastUpdateTime to time.

      4. Let:

         • thresholdIndex be 0.

         • isIntersecting be false.

         • targetRect be a DOMRectReadOnly with x, y, width, and height set to 0.

         • intersectionRect be a DOMRectReadOnly with x, y, width, and height set to 0.

      5. If the intersection root is not the implicit root, and target is not in the same document as the intersection root, skip to step 11.

      6. If the intersection root is an Element, and target is not a descendant of the intersection root in the containing block chain, skip to step 11.

      7. Set targetRect to the DOMRectReadOnly obtained by getting the bounding box for target.

      8. Let intersectionRect be the result of running the compute the intersection algorithm on target and observer’s intersection root.

      9. Let targetArea be targetRect’s area.

      10. Let intersectionArea be intersectionRect’s area.

      11. 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).

      12. 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.

      13. Set thresholdIndex to 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.

      14. Let isVisible be the result of running the visibility algorithm on target.

      15. Let previousThresholdIndex be the registration’s previousThresholdIndex property.

      16. Let previousIsIntersecting be the registration’s previousIsIntersecting property.

      17. Let previousIsVisible be the registration’s previousIsVisible property.

      18. If thresholdIndex does not equal previousThresholdIndex, or if isIntersecting does not equal previousIsIntersecting, or if isVisible does not equal previousIsVisible, queue an IntersectionObserverEntry, passing in observer, time, rootBounds, targetRect, intersectionRect, isIntersecting, isVisible, and target.

      19. Assign thresholdIndex to registration’s previousThresholdIndex property.

      20. Assign isIntersecting to registration’s previousIsIntersecting property.

      21. Assign isVisible to registration’s previousIsVisible 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 the observer’s unobserve() method is called with the target as argument; or the observer’s disconnect() is called.

3.4. External Spec Integrations

3.4.1. HTML Processing Model: Event Loop

An Intersection Observer processing step exists as a substep within the "Update the rendering" step, in the HTML Event Loops Processing Model.

3.4.2. Pending initial IntersectionObserver targets

1. The observer’s root is in the document (for the top-level browsing context, this includes implicit root observers).
2. The observer has at least one target in its [[ObservationTargets]] slot for which no IntersectionObserverEntry has yet been queued.

In the HTML Event Loops Processing Model, under the "Update the rendering" step, the "Unnecessary rendering" step should be modified to add an additional requirement for skipping the rendering update:

• The document does not have pending initial IntersectionObserver targets.

4. Accessibility Considerations

This section is non-normative.

There are no known accessibility considerations for the core IntersectionObserver specification (this document). There are, however, related specifications and proposals that leverage and refer to this spec, which might have their own accessibility considerations. In particular, specifications for HTML § 2.5.7 Lazy loading attributes and CSS Containment 2 § 4 Suppressing An Element’s Contents Entirely: the content-visibility property may have implications for HTML § 6.9 Find-in-page, HTML § 6.6.3 The tabindex attribute, and spatial navigation.

5. Privacy and Security

This section is non-normative.

The main privacy concerns associated with this API relate to the information it may provide to code running in the context of a cross-origin iframe (i.e., the cross-origin-domain target case). In particular:

• There is no universal consensus on the privacy implications of revealing whether an iframe is within the global viewport.

• There is a risk that the API may be used to probe for information about the geometry of the global viewport itself, which may be used to deduce the user’s hardware configuration. The motivation for disabling the effects of rootMargin and scrollMargin, and suppressing rootBounds for cross-origin-domain targets is to prevent such probing.

It should be noted that prior to IntersectionObserver, web developers used other API’s in very ingenious (and grotesque) ways to tease out the information available from IntersectionObserver. As a purely practical matter, this API does not reveal any information that was not already available by other means.

Another consideration is that IntersectionObserver uses DOMHighResTimeStamp, which has privacy and security considerations of its own. It is however unlikely that IntersectionObserver is vulnerable to timing-related exploits. Timestamps are generated at most once per rendering update (see § 3.4.1 HTML Processing Model: Event Loop), which is far too infrequent for the familiar kind of timing attack.

6. Internationalization

This section is non-normative.

There are no known issues concerning internationalization.

7. Acknowledgements

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