index.bs

<pre class='metadata'>
Title: Intersection Observer
Status: ED
ED: https://github.com/slightlyoff/IntersectionObserver/
Shortname: intersection-observer
Level: 1
Editor: Michael Blain, Google, mpb@google.com
Abstract: This specification describes  an API that can be used to understand the visibility and position of DOM elements relative to a viewport. The position is delivered asynchronously and is useful for understanding the visibility of elements and implementing pre-loading and deferred loading of DOM content.
Group: Web Performance Working Group
Repository: slightlyoff/IntersectionObserver
</pre>

<pre class="anchors">
urlPrefix: http://www.w3.org/TR/hr-time/; type: typedef; text: DOMHighResTimeStamp
url: http://w3c.github.io/requestidlecallback/#dfn-list-of-idle-request-callbacks; type: dfn; text: list of idle request callbacks
url: https://html.spec.whatwg.org/multipage/infrastructure.html#dfn-callback-this-value; type: dfn; text: callback this value
urlPrefix: https://html.spec.whatwg.org/multipage/browsers.html; type: dfn; text: unit of related similar-origin browsing contexts
urlPrefix: https://html.spec.whatwg.org/multipage/webappapis.html; type: dfn; text: report the exception
urlPrefix: https://html.spec.whatwg.org/multipage/webappapis.html; type: dfn; text: event loop
urlPrefix: https://html.spec.whatwg.org/multipage/infrastructure.html; type: dfn; text: rules for parsing dimension values
url: https://heycam.github.io/webidl/#dfn-simple-exception; type:exception; text: RangeError
url: https://heycam.github.io/webidl/#dfn-simple-exception; type:exception; text: TypeError
urlPrefix: http://heycam.github.io/webidl/#dfn-; type:dfn; text: throw
url: https://drafts.csswg.org/css2/box.html#content-edge; type:dfn; text: content-box
</pre>

<pre class="link-defaults">
spec:dom-ls; type:interface; text:Document
</pre>

<h2 id='introduction'>Introduction</h2>
    The web's traditional position calculation mechanisms rely on explicit
    queries of DOM state that are known to cause (expensive) style recalcuation
    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):
    <ul>
      <li>Building custom pre- and deferred-loading of DOM and data.</li>
      <li>Implementing data-bound high-performance scrolling lists which load
          and render subsets of data sets. These lists are a central mobile
          interaction idiom.</li>
      <li>Calculating element visibility. In particular,
          <a href="http://www.iab.net/iablog/2014/03/viewability-has-arrived-what-you-need-to-know-to-see-through-this-sea-change.html">
          ad networks now require reporting of ad "visibility" for monetizing
          impressions</a>. This has led to many sites abusing scroll handlers
          (causing jank on scroll),
          <a href="http://gent.ilcore.com/2011/03/how-not-to-trigger-layout-in-webkit.html">
          synchronous layout invoking readbacks</a> (causing unneccessary
          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).</li>
    </ul>

    These use-cases have several common properties:
    <ol>
      <li>They can be represented as passive "queries" about the state of
          individual elements with respect to some other element (or the global
          viewport)</li>
      <li>They do not impose hard latency requirements; that is to say, the
          information can be delivered asynchronously (e.g. from another thread)
          without penalty</li>
      <li>They are poorly supported by nearly all combinations of existing web
          platform features, requiring extraordinary developer effort despite
          their widespread use.</li>
    </ol>

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

    <pre class="example">
      <code highlight="js">
        var observer = new IntersectionObserver(function(changes) {
          for (var i in changes) {
            console.log(changes[i].time);               // Timestamp when the change occurred
            console.log(changes[i].rootBounds);         // Unclipped area of root
            console.log(changes[i].intersectionRect);   // Unclipped area of target intersected with rootBounds
            console.log(changes[i].boundingClientRect); // target.boundingClientRect()
            console.log(changes[i].target);             // the Element target
          }
        }, {});

        // Watch all threshold events on a specific descendant of the viewport
        observer.observe(childElement);

        observer.disconnect(); // removes all
      </code>
    </pre>

<h2 id='intersection-observer-api'>Intersection Observer</h2>
    The <dfn>Intersection Observer</dfn> API enables developers to understand
    the visibility and position of DOM elements relative to a root element or
    the top level document's viewport.

<h3 id='intersection-observer-callback'>
The IntersectionObserverCallback</h3>
    <pre class="idl">
        callback IntersectionObserverCallback = void (sequence&lt;IntersectionObserverEntry> entries, IntersectionObserver observer)
    </pre>
    This callback will be invoked when there are changes to <i>target</i>'s
    intersection with <i>root</i>, as per the <a>processing model</a>.

<h3 id='intersection-observer-interface'>
The IntersectionObserver interface</h3>
    The {{IntersectionObserver}} interface can be used to observe changes in
    the intersection of a <i>target</i> {{Element}} and a <i>root</i>
    {{Element}} (or the top-level document's viewport).

    Note: In {{MutationObserver}}, the {{MutationObserverInit}} options are
    passed to {{MutationObserver/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 IntersectionObserver, having different {{root}},
    {{rootMargin}} or {{threshold}} values for each <i>target</i> 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.

    <pre class="idl">
      [Constructor(IntersectionObserverCallback callback, optional IntersectionObserverInit options), Exposed=Window]
      interface IntersectionObserver {
        void observe (Element target);
        void unobserve (Element target);
        void disconnect ();
        sequence&lt;IntersectionObserverEntry> takeRecords ();
      };
    </pre>

    <div dfn-type="method" dfn-for="IntersectionObserver">
        : <dfn constructor lt="IntersectionObserver(callback, options)">
            new IntersectionObserver(callback, options)</dfn>
        ::
            <ol>
                <li>Let |this| be a new {{IntersectionObserver}} object</li>
                <li>Set |this|'s internal {{[[callback]]}} slot to |callback|.
                    </li>
                <li>Set |this|'s internal {{[[root]]}} slot to
                    |options|.{{root}}</li>
                <li>Set |this|'s internal {{[[rootMargin]]}} slot to
                    |options|.{{rootMargin}}</li>
                <li>Let |thresholds| be a list equal to
                    |options|.{{threshold}}.</li>
                <li>If any value in |thresholds| is less than 0.0 or greater
                    than 1.0, <a>throw</a> a {{RangeError}} exception.</li>
                <li>Sort |thresholds| in ascending order</li>
                <li>If |thresholds| is empty, append <i>0</i> to |thresholds|.
                    </li>
                <li>Set |this|'s internal {{[[threshold]]}} slot to
                    |thresholds|.</li>
                <li>Append |this| to the
                    <a>unit of related similar-origin browsing contexts</a>'s
                    <a>IntersectionObservers</a> list.</li>
                <li>Return |this|.</li>
            </ol>
        : <dfn>observe(target)</dfn>
        ::
            <ol>
                <li>If |target| is in |this|'s internal
                    {{[[ObservationTargets]]}} slot, return.</li>
                <li>If |target| is NOT a descendent of |this|'s internal
                    {{[[root]]}} slot, <a>throw</a> a {{TypeError}}.</li>
                <li>Add |this| to |target|'s internal
                    {{[[RegisteredIntersectionObservers]]}} slot.</li>
                <li>Add |target| to |this|'s internal {{[[ObservationTargets]]}}
                    slot.</li>
            </ol>
        : <dfn>unobserve(target)</dfn>
        ::
            <ol>
                <li>Remove |this| from |target|'s internal
                    {{[[RegisteredIntersectionObservers]]}} slot.</li>
                <li>Remove |target| from |this|'s internal
                    {{[[ObservationTargets]]}} slot.</li>
            </ol>

            Note: {{MutationObserver}} does not implement {{unobserve()}}.
            For IntersectionObserver, {{unobserve()}} addresses the lazy-loading
            use case. After a <i>target</i> becomes visible, it does not need
            to be tracked. It would be more work to either {{disconnect()}} all
            <i>targets</i> and {{observe()}} the remaining ones, or create a
            separate {{IntersectionObserver}} for each <i>target</i>.
        : <dfn>disconnect()</dfn>
        ::
            For each |target| in |this|'s internal {{[[ObservationTargets]]}}
            slot
            <ol>
                <li>Remove |this| from |target|'s internal
                    {{[[RegisteredIntersectionObservers]]}} slot.</li>
                <li>Remove |target| from |this|'s internal
                    {{[[ObservationTargets]]}} slot.</li>
            </ol>
        : <dfn>takeRecords()</dfn>
        ::
            <ol>
                <li>Let |queue| be a copy of |this|'s internal
                    {{[[QueuedEntries]]}} slot.</li>
                <li>Clear |this|'s internal {{[[QueuedEntries]]}} slot.</li>
                <li>Return |queue|.</li>
            </ol>
    </div>

<h3 id="intersection-observer-entry">
The IntersectionObserverEntry interface</h3>
    <pre class="idl">
      [Constructor(IntersectionObserverEntryInit intersectionObserverEntryInit)]
      interface IntersectionObserverEntry {
        readonly attribute DOMHighResTimeStamp time;
        readonly attribute DOMRectReadOnly rootBounds;
        readonly attribute DOMRectReadOnly boundingClientRect;
        readonly attribute DOMRectReadOnly intersectionRect;
        readonly attribute Element target;
      };

      dictionary IntersectionObserverEntryInit {
        required DOMHighResTimeStamp time;
        required DOMRectInit rootBounds;
        required DOMRectInit boundingClientRect;
        required DOMRectInit intersectionRect;
        required Element target;
      };

    </pre>

    <div dfn-type="attribute" dfn-for="IntersectionObserverEntry">
        : <dfn>boundingClientRect</dfn>
        ::
            The {{DOMRect}} corresponding to the <i>target</i>'s
            {{Element/getBoundingClientRect()}}.
        : <dfn>intersectionRect</dfn>
        ::
            The {{DOMRect}} corresponding to <i>boundingClientRect</i>
            intersected by each of <i>target</i>'s ancestors' clip rects
            (up to but not including {{root}}), intersected with
            {{IntersectionObserverEntry/rootBounds}}. This value represents the
            portion of <i>target</i> actually visible within
            {{IntersectionObserverEntry/rootBounds}}.
        : <dfn>rootBounds</dfn>
        ::
            The visible dimensions of {{root}}, adjusted by {{rootMargin}},
            in the coordinate space of the document the root element is in. If
            {{root}} is undefined, then use the coordinate space of the
            top-level document.
        : <dfn>target</dfn>
        ::
            The {{Element}} whose intersection with {{root}} changed.
        : <dfn>time</dfn>
        ::
            The attribute must return a {{DOMHighResTimeStamp}} that
            corresponds to the time the intersection was recorded.
    </div>
<h3 id="intersection-observer-init">
The IntersectionObserverInit dictionary</h3>
    <pre class="idl">
      dictionary IntersectionObserverInit {
        Element?  root = null;
        DOMString rootMargin = "0px";
        (double or sequence&lt;double>) threshold = 0;
      };
    </pre>

    <div dfn-type="dict-member" dfn-for="IntersectionObserverInit">
        : <dfn>root</dfn>
        ::
            The <i>root</i> to use for intersection. If not provided, use the
            top-level document's viewport.
        : <dfn>rootMargin</dfn>
        ::
            Same as 'margin', can be 1, 2, 3 or 4 components, possibly
            negative lengths.

            If there is only one component value, it applies to all sides.
            If there are two values, the top and bottom margins are set to
            the first value and the right and left margins are set to the
            second. If there are three values, the top is set to the first
            value, the left and right are set to the second, and the bottom
            is set to the third. If there are four values, they apply to the
            top, right, bottom, and left, respectively.e.g.
            <pre class="example">
              <code class="js">
                "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
              </code>
            </pre>
        : <dfn>threshold</dfn>
        ::
            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 as specified by
            <i>target</i>.{{Element/getBoundingClientRect()}}.

            Note: 0.0 is effectively "any non-zero number of pixels".
    </div>

<h2 id='intersection-observer-processing-model'><dfn>Processing Model</dfn></h3>
    This section outlines the steps the user agent must take when implementing
    the <a>Intersection Observer</a> API.

<h3 id='defines'>Internal Slot Definitions</h2>

<h4 id='browsing-contexts-defines'>Browsing Contexts</h4>
    Each <a>unit of related similar-origin browsing contexts</a> has an
    <dfn for="browsing context">IntersectionObserverTaskQueued</dfn> flag which
    is initialized to false and an <dfn for="browsing context">
    IntersectionObservers</dfn> list which is initially empty.

<h4 id='element-private-slots'>Element</h4>
    {{Element}} objects have an internal
    <dfn attribute for=Element>\[[RegisteredIntersectionObservers]]</dfn> slot,
    which is initialized to an empty list and an internal
    <dfn attribute for=Element>\[[PreviousVisibleRatio]]</dfn> slot, which is
    initialized to 0.

<h4 id='intersection-observer-private-slots'>IntersectionObserver</h4>
    {{IntersectionObserver}} objects have internal
    <dfn attribute for=IntersectionObserver>\[[QueuedEntries]]</dfn> and
    <dfn attribute for=IntersectionObserver>\[[ObservationTargets]]</dfn> slots,
    which are initialized to empty lists and internal
    <dfn attribute for=IntersectionObserver>\[[callback]]</dfn>,
    <dfn attribute for=IntersectionObserver>\[[root]]</dfn>,
    <dfn attribute for=IntersectionObserver>\[[rootMargin]]</dfn> and
    <dfn attribute for=IntersectionObserver>\[[threshold]]</dfn> slots, which
    are initialized by <a>IntersectionObserver(callback, options)</a>.

<h3 id='algorithms'>Algorithms</h2>

<h4 id='queue-intersection-observer-task'>Queue an Intersection Observer Task
</h4>
    To <dfn>queue an intersection observer task</dfn> for a <a>unit of related
    similar-origin browsing contexts</a> |unit|, run these steps:
    <ol>
        <li>If |unit|'s <a>IntersectionObserverTaskQueued</a> flag is set to
            true, return.</li>
        <li>Set |unit|'s <a>IntersectionObserverTaskQueued</a> flag to true.
            </li>
        <li>Post a task to <a>notify intersection observers</a>, or enqueue a
            task to <a>notify intersection observers</a> in the
            <a>list of idle request callbacks</a> with an appropriate |timeout|.

            Issue: Should we define an appropriate |timeout|?
        </li>
    </ol>

<h4 id='notify-intersection-observers-algo'>Notify Intersection Observers</h4>
    To <dfn>notify intersection observers</dfn> for a <a>unit of related
    similar-origin browsing contexts</a> |unit|, run these steps:
    <ol>
        <li>Set |unit|'s <a>IntersectionObserverTaskQueued</a> flag to false.
            </li>
        <li>Let |notify list| be a copy of |unit|'s <a>IntersectionObservers</a>
            list.</li>
        <li>For each {{IntersectionObserver}} object |observer| in
            |notify list|, run these steps:</li>
            <ol>
                <li>If |observer|'s internal {{[[QueuedEntries]]}} slot is
                    empty, continue.</li>
                <li>Let |queue| be a copy of |observer|'s internal
                    {{[[QueuedEntries]]}} slot.</li>
                <li>Clear |observer|'s internal {{[[QueuedEntries]]}} slot.</li>
                <li>Invoke |callback| with |queue| as the first argument and
                    |observer| as the second argument and
                    <a>callback this value</a>. If this throws an exception,
                    <a>report the exception</a>.</li>
            </ol>
    </ol>

<h4 id='queue-intersection-observer-entry-algo'>Queue an
IntersectionObserverEntry</dfn></h4>
    To <dfn>queue an IntersectionObserverEntry</dfn> for |observer|, given a
    <a>unit of related similar-origin browsing contexts</a> |unit|, |observer|,
    |time|, |rootBounds|, |boundingClientRect|, |intersectionRect| and |target|,
    run these steps:
    <ol>
        <li>Construct an {{IntersectionObserverEntry}}, passing in |time|,
            |rootBounds|, |boundingClientRect|, |intersectionRect| and |target|.
            </li>
        <li>Append it to |observer|'s internal {{[[QueuedEntries]]}} slot.</li>
        <li><a>Queue an intersection observer task</a> for |unit|.</li>
    </ol>

<h4 id='update-intersection-observations-algo'>Run the Update Intersection
Observations Steps</h4>
    To <dfn>run the update intersection observations steps</dfn> for an
    <a>event loop</a> |loop| given a timestamp |time|, run these steps:
    <ul>
        <li>Let |unit| be the
            <a>unit of related similar-origin browsing contexts</a> for |loop|.
            </li>
        <li>For each |observer| in |unit|'s <a>IntersectionObservers</a> list
            </li>
            <ul>
                <li>Let |rootBounds| be the <a>content-box</a> of |observer|'s
                    internal {{[[root]]}} slot (or the top-level document's
                    viewport), adjusted by |observer|'s internal
                    {{[[rootMargin]]}} slot.</li>
                <li>For each |target| in |observer|'s internal
                    {{[[ObservationTargets]]}} slot</li>
                <ol>
                    <li>Let |boundingClientRect| be the value of
                        |target|.{{Element/getBoundingClientRect()}}.</li>
                    <li>Let |intersectionRect| be the intersection of
                        |boundingClientRect| with |rootBounds|, intersected with
                        the clip rect of each ancestor between |target| and
                        |observer|'s internal {{[[root]]}} slot.</li>

                        Issue: TBD: Do the <i>clip rect</i>s include 'clip-path'
                        and other clipping properties or just overflow clipping?
                    <li>Let |area| be |boundingClientRect|'s area.</li>
                    <li>Let |visibleArea| be |intersectionRect|'s area.</li>
                    <li>Let |visibleRatio| be |visibleArea| divided by |area| if
                        |area| is non-zero, and <i>0</i> otherwise.</li>
                    <li>Let |threshold| be the index of the first entry in
                        |observer|'s internal {{[[threshold]]}} slot whose value
                        is greater than or equal to |visibleRatio|. If
                        |visibleRatio| is equal to <i>0</i>, let |threshold| be
                        <i>-1</i>.</li>
                    <li>Let |oldVisibleRatio| be set to |target|'s internal
                        {{[[PreviousVisibleRatio]]}} slot.</li>
                    <li>Let |oldThreshold| be the index of the first entry in
                        |observer|'s internal {{[[threshold]]}} slot whose value
                        is greater than or equal to |oldVisibleRatio|. If
                        |oldVisibleRatio| is equal to <i>0</i>, let
                        |oldThreshold| be <i>-1</i>.</li>
                    <li>If |threshold| does not equal |oldThreshold|,
                        <a>queue an IntersectionObserverEntry</a> for |unit|,
                        passing in |observer|, |time|, |rootBounds|,
                        |boundingClientRect|, |intersectionRect| and |target|.
                        </li>
                    <li>Assign |visibleRatio| to |target|'s internal
                        {{[[PreviousVisibleRatio]]}} slot.</li>
                </ol>
            </ul>
        </ul>

<h4 id='removing-steps'>Removing Steps</h4>
    Whenever the <a>removing steps</a> run with an |oldNode|, run these steps:

    <ol>
        <li>Let |nodes| be |oldNode|'s <a>inclusive descendants</a>, in
            <a>tree order</a>.
        <li>For each |node| in |nodes|, run this substep:
        <ol>
            <li>For each |observer| in |node|'s internal
                {{[[RegisteredIntersectionObservers]]}} slot, run the
                {{unobserve()}} algorithm on |observer|, passing in |node| as
                |target|.</li>
        </ol>
    </ol>

<h3 id='external-spec-integrations'>External Spec Integrations</h3>

<h4 id='event-loop'>HTML Processing Model: Event Loop</h4>
    An <a>Intersection Observer</a> processing step should take place AFTER the
    layout and rendering steps have been performed in the
    <a href="https://html.spec.whatwg.org/multipage/webappapis.html#processing-model-8">
    update the rendering</a> event loop in the HTML Processing Model.

    This step is:
    <ol start="11">
        <li><a>Run the update intersection observations steps</a> for the
            <a>event loop</a> in question, passing in <i>now</i> as the
            timestamp.</li>
    </ol>