Intersection Observer

Editor’s Draft,

This version:
https://w3c.github.io/IntersectionObserver/
Latest published version:
https://www.w3.org/TR/intersection-observer/
Test Suite:
http://w3c-test.org/intersection-observer/
Issue Tracking:
GitHub
Editor:
(Google)
Former Editor:
(Google)

Abstract

This specification describes an API that can be used to understand the visibility and position of DOM elements ("targets") relative to a containing element or to the top-level viewport ("root"). The position is delivered asynchronously and is useful for understanding the visibility of elements and implementing pre-loading and deferred loading of DOM content.

Status of this document

This section describes the status of this document at the time of its publication. Other documents may supersede this document. A list of current W3C publications and the latest revision of this technical report can be found in the W3C technical reports index at https://www.w3.org/TR/.

This document was published by the Web Platform Working Group as an Editors Draft. This document is intended to become a W3C Recommendation.

Feedback and comments on this specification are welcome, please send them to public-webapps@w3.org (subscribe, archives) with [intersection-observer] at the start of your email’s subject.

Publication as an Editors Draft does not imply endorsement by the W3C Membership. This is a draft document and may be updated, replaced or obsoleted by other documents at any time. It is inappropriate to cite this document as other than work in progress.

This document was produced by a group operating under the 5 February 2004 W3C Patent Policy. W3C maintains a public list of any patent disclosures made in connection with the deliverables of the group; that page also includes instructions for disclosing a patent. An individual who has actual knowledge of a patent which the individual believes contains Essential Claim(s) must disclose the information in accordance with section 6 of the W3C Patent Policy.

This document is governed by the 1 March 2017 W3C Process Document.

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

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 sequence<double> thresholds;
  void observe(Element target);
  void unobserve(Element target);
  void disconnect();
  sequence<IntersectionObserverEntry> takeRecords();
};
new IntersectionObserver(callback, options)
  1. Let this be a new IntersectionObserver object

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

  3. Set this.root to options.root.

  4. Attempt to parse a root margin from options.rootMargin. If a list is returned, set this’s internal [[rootMargin]] 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. Set this.thresholds to thresholds.

  10. Return this.

observe(target)
  1. If target is in this’s internal [[ObservationTargets]] slot, return.

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

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

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

  5. Schedule an iteration of the event loop in the root's browsing context.

unobserve(target)
  1. Remove the IntersectionObserverRegistration record whose observer property is equal to this from target’s internal [[RegisteredIntersectionObservers]] slot.

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

Note: MutationObserver does not implement unobserve(). For IntersectionObserver, unobserve() addresses the lazy-loading use case. After target becomes visible, it does not need to be tracked. It would be more work to either disconnect() all targets and observe() the remaining ones, or create a separate IntersectionObserver for each target.

disconnect()

For each target in this’s internal [[ObservationTargets]] slot:

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

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

takeRecords()
  1. Let queue be a copy of this’s internal [[QueuedEntries]] slot.

  2. Clear this’s internal [[QueuedEntries]] slot.

  3. Return queue.

root, of type Element, readonly, nullable

The root Element to use for intersection, or null if the observer uses the implicit root.

rootMargin, of type DOMString, readonly

Offsets applied to the intersection root’s bounding box, effectively growing or shrinking the box that is used to calculate intersections. Note that rootMargin is only applied for targets which belong to the same unit of related similar-origin browsing contexts as the intersection root.

On getting, return the result of serializing the elements of [[rootMargin]] space-separated, where pixel lengths serialize as the numeric value followed by "px", and percentages serialize as the numeric value followed by "%". Note that this is not guaranteed to be identical to the options.rootMargin passed to the IntersectionObserver constructor. If no rootMargin was passed to the IntersectionObserver constructor, the value of this attribute is "0px 0px 0px 0px".

thresholds, of type sequence<double>, readonly

A list of thresholds, sorted in increasing numeric order, where each threshold is a ratio of intersection area to bounding box area of an observed target. Notifications for a target are generated when any of the thresholds are crossed for that target. If no options.threshold was provided to the IntersectionObserver constructor, the value of this attribute will be [0].

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;
};
boundingClientRect, of type DOMRectReadOnly, readonly

A DOMRectReadOnly obtained by running the getBoundingClientRect() algorithm on the target.

intersectionRect, of type DOMRectReadOnly, readonly

boundingClientRect, intersected by each of target's ancestors' clip rects (up to but not including root), intersected with the root intersection rectangle. This value represents the portion of target actually visible within the root intersection rectangle.

isIntersecting, of type boolean, readonly

True if the target intersects with the root; false otherwise. This flag makes it possible to distinguish between an IntersectionObserverEntry signalling the transition from intersecting to not-intersecting; and an IntersectionObserverEntry signalling a transition from not-intersecting to intersecting with a zero-area intersection rect (as will happen with edge-adjacent intersections, or when the boundingClientRect has zero area).

intersectionRatio, of type double, readonly

If the boundingClientRect has non-zero area, this will be the ratio of intersectionRect area to boundingClientRect area. Otherwise, this will be 1 if the isIntersecting is true, and 0 if not.

rootBounds, of type DOMRectReadOnly, readonly

If target belongs to the same unit of related similar-origin browsing contexts as the intersection root, this will be the root intersection rectangle. Otherwise, this will be null. Note that if the target is in a different browsing context than the intersection root, this will be in a different coordinate system than boundingClientRect and intersectionRect.

target, of type Element, readonly

The Element whose intersection with the intersection root changed.

time, of type DOMHighResTimeStamp, readonly

The attribute must return a DOMHighResTimeStamp that corresponds to the time the intersection was recorded, relative to the time origin of the global object associated with the IntersectionObserver instance that generated the notification.

2.4. The IntersectionObserverInit dictionary

dictionary IntersectionObserverInit {
  Element?  root = null;
  DOMString rootMargin = "0px";
  (double or sequence<double>) threshold = 0;
};
root, of type Element, nullable, defaulting to null

The root to use for intersection. If not provided, use the implicit root.

rootMargin, of type DOMString, defaulting to "0px"

Similar to the CSS margin property, this is a string of 1-4 components, each either an absolute length or a percentage.

"5px"                // all margins set to 5px
"5px 10px"           // top & bottom = 5px, right & left = 10px
"-10px 5px 8px"      // top = -10px, right & left = 5px, bottom = 8px
"-10px -5px 5px 8px" // top = -10px, right = -5px, bottom = 5px, left = 8px
threshold, of type (double or sequence<double>), defaulting to 0

List of threshold(s) at which to trigger callback. callback will be invoked when intersectionRect’s area changes from greater than or equal to any threshold to less than that threshold, and vice versa.

Threshold values must be in the range of [0, 1.0] and represent a percentage of the area of the rectangle produced by running the getBoundingClientRect() algorithm on the target.

Note: 0.0 is effectively "any non-zero number of pixels".

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:

An IntersectionObserver will continue observing a target until any of the following occurs:

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:

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

Conformance

Document conventions

Conformance requirements are expressed with a combination of descriptive assertions and RFC 2119 terminology. The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in the normative parts of this document are to be interpreted as described in RFC 2119. However, for readability, these words do not appear in all uppercase letters in this specification.

All of the text of this specification is normative except sections explicitly marked as non-normative, examples, and notes. [RFC2119]

Examples in this specification are introduced with the words “for example” or are set apart from the normative text with class="example", like this:

This is an example of an informative example.

Informative notes begin with the word “Note” and are set apart from the normative text with class="note", like this:

Note, this is an informative note.

Conformant Algorithms

Requirements phrased in the imperative as part of algorithms (such as "strip any leading space characters" or "return false and abort these steps") are to be interpreted with the meaning of the key word ("must", "should", "may", etc) used in introducing the algorithm.

Conformance requirements phrased as algorithms or specific steps can be implemented in any manner, so long as the end result is equivalent. In particular, the algorithms defined in this specification are intended to be easy to understand and are not intended to be performant. Implementers are encouraged to optimize.

.

Index

Terms defined by this specification

Terms defined by reference

References

Normative References

[CSS-SYNTAX-3]
Tab Atkins Jr.; Simon Sapin. CSS Syntax Module Level 3. 20 February 2014. CR. URL: https://www.w3.org/TR/css-syntax-3/
[CSS-VALUES-3]
Tab Atkins Jr.; Elika Etemad. CSS Values and Units Module Level 3. 29 September 2016. CR. URL: https://www.w3.org/TR/css-values-3/
[CSS22]
Bert Bos. Cascading Style Sheets Level 2 Revision 2 (CSS 2.2) Specification. 12 April 2016. WD. URL: https://www.w3.org/TR/CSS22/
[CSSOM-VIEW-1]
Simon Pieters. CSSOM View Module. 17 March 2016. WD. URL: https://www.w3.org/TR/cssom-view-1/
[DOM]
Anne van Kesteren. DOM Standard. Living Standard. URL: https://dom.spec.whatwg.org/
[GEOMETRY-1]
Simon Pieters; Dirk Schulze; Rik Cabanier. Geometry Interfaces Module Level 1. 25 November 2014. CR. URL: https://www.w3.org/TR/geometry-1/
[RFC2119]
S. Bradner. Key words for use in RFCs to Indicate Requirement Levels. March 1997. Best Current Practice. URL: https://tools.ietf.org/html/rfc2119
[WebIDL]
Cameron McCormack; Boris Zbarsky; Tobie Langel. Web IDL. 15 December 2016. ED. URL: https://heycam.github.io/webidl/

IDL Index

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

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

[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;
};

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