Overview.bs

<link href='web-animations.css' rel='stylesheet' type='text/css'>
<pre class='metadata'>
Title: Scroll-linked Animations
Group: CSSWG
Status: ED
Work Status: exploring
Level: 1
Group: CSSWG
URL: https://drafts.csswg.org/scroll-animations-1/
ED: https://drafts.csswg.org/scroll-animations-1/
Shortname: scroll-animations-1
Abstract: Defines an API and markup for creating animations that are tied to
          the scroll offset of a scroll container.
Editor: Brian Birtles, Invited Expert, brian@birchill.co.jp, w3cid 43194
Editor: Botond Ballo, Mozilla, botond@mozilla.com
Editor: Antoine Quint, Apple, graouts@apple.com, w3cid 51377
Editor: Majid Valipour, Google, majidvp@google.com, w3cid 81464
Editor: Olga Gerchikov, Microsoft, gerchiko@microsoft.com

Former editor: Mantaroh Yoshinaga
Former editor: Stephen McGruer, Google, smcgruer@google.com
</pre>
<pre class=anchors>
urlPrefix: https://w3c.github.io/web-animations/; type: dfn; spec: web-animations
    text: animation; url: concept-animation
    text: current time
    text: default document timeline
    text: duration
    text: inactive timeline
    text: start delay
    text: target effect end
    text: timeline
    text: phase; url: timeline-phase
    text: inactive phase; url: timeline-inactive-phase
    text: before phase; url: timeline-before-phase
    text: active phase; url: timeline-active-phase
    text: after phase; url: timeline-after-phase
urlPrefix: https://drafts.csswg.org/cssom-view/; type: dfn; spec: cssom-view-1
    text: CSS layout box
    text: overflow direction; url: overflow-directions
urlPrefix: https://html.spec.whatwg.org/multipage/browsers.html; type: dfn; spec: html
    text: document associated with a window; url: concept-document-window
</pre>
<pre class=link-defaults>
spec:html; type:dfn; for:/; text:browsing context
spec:html; type:method; text:requestAnimationFrame()
</pre>

# Introduction # {#intro}

This specification defines mechanisms for
[[#scroll-driven-animations|driving the progress of an animation]] based
on the scroll progress of a scroll container.

## Relationship to other specifications ## {#other-specs}

Web Animations [[WEB-ANIMATIONS-1]] defines an abstract conceptual model for
animations on the Web platform, with elements of the model including
[=animations=] and their [=timelines=],
and associated programming interfaces.

This specification extends this model by defining a new type of animation [=timeline=]:
a [=scroll timeline=].

This specification defines both programming interfaces for interacting with these
concepts, as well as CSS markup which applies these concepts to CSS Animations
[[CSS3-ANIMATIONS]].

The behavior of the CSS markup is described in terms of the programming interfaces.
User agents that do not support script may still implement the CSS markup
provided it behaves as if the underlying programming interfaces were in place.

## Relationship to asynchronous scrolling ## {#async-scrolling}

Some user agents support scrolling that is asynchronous with respect to layout
or script. This specification is intended to be compatible with such an
architecture.

Specifically, this specification allows expressing scroll-linked effects in a
way that does not require script to run each time the effect is sampled. User
agents that support asynchronous scrolling are allowed (but not required) to
sample such effects asynchronously as well.

## Value Definitions ## {#values}

This specification follows the <a href="https://www.w3.org/TR/CSS2/about.html#property-defs">CSS property definition conventions</a> from [[!CSS2]]
using the <a href="https://www.w3.org/TR/css-values-3/#value-defs">value definition syntax</a> from [[!CSS-VALUES-3]].
Value types not defined in this specification are defined in CSS Values &amp; Units [[!CSS-VALUES-3]].
Combination with other CSS modules may expand the definitions of these value types.

In addition to the property-specific values listed in their definitions,
all properties defined in this specification
also accept the <a>CSS-wide keywords</a> keywords as their property value.
For readability they have not been repeated explicitly.

# Use cases # {#use-cases}

<em>This section is non-normative</em>

Note: Based on this <a
href="https://github.com/w3c/csswg-drafts/blob/master/scroll-animations-1/Use%20cases.md">curated
list of use cases</a>.

Issue(4354): These use cases need updating.

## Scrollable picture-story show ## {#scrollable-animation-usecase}

It is sometimes desired to use an animation to tell a story where the user
controls the progress of the animation by scrolling or some other
gesture. This may be because the animation contains a lot of textual
information which the user may wish to peruse more slowly, it may be for
accessibility considerations to accommodate users who are uncomfortable
with rapid animation, or it may simply be to allow the user to easily
return to previous parts of the story such as a story that introduces
a product where the user wishes to review previous information.

The following (simplified) example shows two balls colliding. The
animation is controlled by scroll position allowing the user to easily
rewind and replay the interaction.

<figure>
<img src="img/usecase3-1.svg" width="600"
alt="Use case: The picture-story show.">
 <figcaption>
  A scrollable movie.<br>
  The left figure shows the initial position of the balls<br>
  The right figure shows them after they have collided.
 </figcaption>
</figure>

Using the CSS markup:

<pre class='lang-css'>
@media (prefers-reduced-motion: no-preference) {
  div.circle {
    animation-duration: 1s;
    animation-timing-function: linear;
    animation-timeline: collision-timeline;
  }
  #left-circle {
    animation-name: left-circle;
  }
  #right-circle {
    animation-name: right-circle;
  }
  #union-circle {
    animation-name: union-circle;
    animation-fill-mode: forwards;
    animation-timeline: union-timeline;
  }

  @scroll-timeline collision-timeline {
    source: selector(#container);
    orientation: block;
    start:  200px;
    end: 300px;
  }

  @scroll-timeline union-timeline {
    source: selector(#container);
    orientation: block;
    start:  250px;
    end: 300px;
  }

  @keyframes left-circle {
    to { transform: translate(300px) }
  }
  @keyframes right-circle {
    to { transform: translate(350px) }
  }
  @keyframes union-circle {
    to { opacity: 1 }
  }
}
</pre>

Using the programming interface, we might write this as:

<pre class='lang-javascript'>
if (window.matchMedia('(prefers-reduced-motion: no-preference)').matches) {
  const scrollableElement = document.querySelector('#container');

  const collisionTimeline = new ScrollTimeline({
    source: scrollableElement,
    start: '200px',
    end: '300px'
  });

  const left = leftCircle.animate({ transform: 'translate(300px)' }, 1000);
  left.timeline = collisionTimeline;

  const right = leftCircle.animate({ transform: 'translate(350px)' }, 1000);
  right.timeline = collisionTimeline;

  const union = unionCircle.animate({ opacity: 1 }, { duration: 1000, fill: "forwards" });
  union.timeline = new ScrollTimeline({
    source: scrollableElement,
    start: '250px',
    end: '300px'
  });
}
</pre>

## The content progress bar ## {#content-progress-bar-usecase}

Another common example of an animation that tracks scroll position is a
progress bar that is used to indicate the reader's position in a long
article.

<figure>
<img src="img/usecase3-2.svg" width="600"
alt="Use case: Scroll based styling">
 <figcaption>
  Content progress bar.<br>
  The left figure shows the initial state before scrolling.<br>
  The right figure shows the progress bar is half-filled in since the
  user has scrolled half way through the article.
 </figcaption>
</figure>

Typically, the scroll bar provides this visual indication but
applications may wish to hide the scroll bar for aesthetic or useability
reasons.

Using the updated 'animation' shorthand that includes 'animation-timeline',
this example could be written as follows:

<pre class='lang-css'>
@media (prefers-reduced-motion: no-preference) {
  @scroll-timeline progress-timeline {
    source: selector(#body);
  }

  @keyframes progress {
    to { width: 100%; }
  }
  #progress {
    width: 0px;
    height: 30px;
    background: red;
    animation: 1s linear forwards progress progress-timeline;
  }
}
</pre>


If we use this API for this case, the example code will be as follow:

<pre class='lang-javascript'>
if (window.matchMedia('(prefers-reduced-motion: no-preference)').matches) {
  var animation = div.animate({ width: '100%' }, { duration: 1000, fill: "forwards" });
  animation.timeline = new ScrollTimeline(
    { start: '0px' }
  );
}
</pre>

## Combination scroll and time-base animations ## {#combination-scroll-and-time-base-animations-usecase}

### Photo viewer ### {#movie-show-case-usecase}

Advisement: We are currently reworking this use case

<!--
Maybe the developer will want to use the scroll based timeline and the time-based timeline.

Here's an example content which showing the photos.
If scroll position is out of specified range, the animation of the slideshow will start. The progress of this slideshow is related to scroll volume. And if scroll position is within the specified range, the animation of the slideshow will continue automatically.

<figure>
<img src="img/usecase4.svg" width="600"
alt="Use case 4: Scrollable slide show.">
 <figcaption>
  Use case 4: Scrollable slide show.<br>
  The left figure is before scroll, the slide show will start as scroll-linked animation.<br>
  The right figure is after scroll, the slide show will start as related to the time animation.
 </figcaption>
</figure>

This content can't build the CSS only.
<pre class='lang-javascript'>
if (window.matchMedia('(prefers-reduced-motion: no-preference)').matches) {
  var animation = slideTarget.getAnimation()[0];
  var scrollTimeline = new ScrollTimeline({
    source: scrollableElement,
    orientation: "vertical",
    scrollOffset: '0px',
    end: '200px'
  });
  animation.timeline = scrollTimeline;

  // We use scroll event in order to change the timeline.
  scrollableElement.addEventListener("scroll", function(evt) {
    if ((scrollableElement.scrollTop > 200) && animation.timeline != document.timeline) {
      animation.timeline = document.timeline;
    } else if ((scrollableElement.scrollTop < 200) && animation.timeline == document.timeline) {
      animation.timeline = scrollTimeline;
    }
  });
}
</pre>
-->

</div>

# Scroll-driven animations # {#scroll-driven-animations}

## Scroll timelines ## {#scroll-timelines}

### The {{ScrollDirection}} enumeration ### {#scrolldirection-enumeration}

<pre class="idl">
enum ScrollDirection {
  "block",
  "inline",
  "horizontal",
  "vertical"
};
</pre>

The {{ScrollDirection}} enumeration specifies a direction of scroll of a
scrollable element.

:   <code>block</code>
::  Selects the direction along the [=block axis=], conforming to writing mode
    and directionality.

:   <code>inline</code>
::  Selects the direction along the [=inline axis=], confirming to writing mode
    and directionality.

:   <code>horizontal</code>
::  Selects the physical horizontal direction (ignoring writing mode and
    directionality).

:   <code>vertical</code>
::  Selects the physical vertical direction (ignoring writing mode and
    directionality).

Note: Having both logical (block/inline) and physical (vertical/horizontal)
directions allows web developers to animate both logical (e.g.
margin-inline-start) and physical (e.g. transform) properties with good
behavior under different directionalities and writing modes.

### The {{ScrollTimeline}} interface ### {#scrolltimeline-interface}

<pre class="idl">
enum ScrollTimelineAutoKeyword { "auto" };

dictionary ScrollTimelineOptions {
  Element? source = null;
  ScrollDirection orientation = "block";
  (DOMString or ElementBasedOffset) start = "auto";
  (DOMString or ElementBasedOffset) end = "auto";
  (double or ScrollTimelineAutoKeyword) timeRange = "auto";
};

[Exposed=Window]
interface ScrollTimeline : AnimationTimeline {
  constructor(optional ScrollTimelineOptions options = {});
  readonly attribute Element? source;
  readonly attribute ScrollDirection orientation;
  readonly attribute (DOMString or ElementBasedOffset) start;
  readonly attribute (DOMString or ElementBasedOffset) end;
  readonly attribute (double or ScrollTimelineAutoKeyword) timeRange;
};
</pre>

A <dfn>scroll timeline</dfn> is an {{AnimationTimeline}} whose time values are
determined not by wall-clock time, but by the progress of scrolling in a
[=scroll container=].

<div link-for-hint="ScrollTimeline">

<div class="constructors">

:   <dfn constructor for=ScrollTimeline lt="ScrollTimeline(options)">ScrollTimeline(options)</dfn>
::  Creates a new {{ScrollTimeline}} object using the following procedure:

    1.  Let |timeline| be a new {{ScrollTimeline}} object.

    1.  Let |source| be the result corresponding to the first matching condition
        from the following:

        <div class="switch">

        :   If the <code>source</code> member of |options| is missing,
        ::  The {{scrollingElement}} of the {{Document}} <a lt="document
            associated with a window">associated</a> with the {{Window}} that is
            the <a>current global object</a>.

        :   Otherwise,
        ::  The <code>source</code> member of |options|.

        </div>

    1.  Set the {{ScrollTimeline/source}} of |timeline| to |source|.

    1.  Assign the {{ScrollTimeline/orientation}}, {{ScrollTimeline/start}},
        {{ScrollTimeline/end}}, and {{ScrollTimeline/timeRange}} properties of
        |timeline| to the corresponding value from |options|.

</div>

<div class="attributes">

:   <dfn attribute for=ScrollTimeline>source</dfn>
::  The scrollable element whose scrolling triggers the activation and drives
    the progress of the timeline.

:   <dfn attribute for=ScrollTimeline>orientation</dfn>
::  Determines the direction of scrolling which triggers the activation and
    drives the progress of the timeline.

:   <dfn attribute for=ScrollTimeline>start</dfn>
::  A [=scroll timeline offset=] which determines the [=effective scroll
    offset=] in the direction specified by {{orientation}} that constitutes the
    beginning of the range in which the timeline is active.

:   <dfn attribute for=ScrollTimeline>end</dfn>
::  A [=scroll timeline offset=] which determines the [=effective scroll
    offset=] in the direction specified by {{orientation}} that constitutes the
    end of the range in which the timeline is active.

:   <dfn attribute for=ScrollTimeline>timeRange</dfn>
::  A time duration that allows mapping between a distance scrolled, and
    quantities specified in time units, such as an animation's [=duration=] and
    [=start delay=].

    Conceptually, {{timeRange}} represents the number of milliseconds to map to
    the scroll range defined by {{start}} and {{end}}. As a result, this value
    does not have a correspondence to wall-clock time.

    This value is used to compute the timeline's [=effective time range=], and
    the mapping is then defined by mapping the scroll distance from
    {{start}} to {{end}}, to the [=effective time range=].

Issue(4862): We are working to remove the need for {{timeRange}} to be declared.
The most recent work on this involved introduction of the concept of
"progress-based animations" to web animations.

</div>

### Scroll Timeline Offset ### {#scroll-timeline-offset-section}

An <dfn>effective scroll offset</dfn> is a scroll position for a given [=scroll
container=] and on a given scroll direction.

A <dfn>scroll timeline offset</dfn> is provided by authors and determines a
[=effective scroll offset=] for the {{source}} and in the direction specified by
{{orientation}}.

There are two types of scroll timeline offset: [=container-based offset=], and
[=element-based offset=]. To <dfn>resolve a scroll timeline offset</dfn> into an
[=effective scroll offset=], run the procedure to [=resolve a container-based
offset=] or to [=resolve an element-based offset=] depending on the offset type.
It is possible for a [=scroll timeline offset=] to be resolved to null.

The <dfn>effective start offset</dfn> is the [=effective scroll offset=] that is
resolved from {{start}}. The <dfn>effective end offset</dfn> is
the [=effective scroll offset=] that is resolved from {{end}}.

#### Container-based Offset #### {#container-based-offset-section}
A <dfn>container-based offset</dfn> is a scroll timeline offset that is declared
only in relation with the <a>scroll container</a> as specified by {{source}}.

A [=container-based offset=] is provided in the {{DOMString}} form and can have
one the following values:

*   auto
*   <<length-percentage>>


The procedure to <dfn>resolve a container-based offset</dfn> given
<var>offset</var> is as follows:

1.  If <em>any</em> of the following are true:

    * {{source}} is null, or
    * {{source}} does not currently have a [=CSS layout box=], or
    * {{source}}'s layout box is not a [=scroll container=].

    The [=effective scroll offset=] is null and abort remaining steps.

1.  The [=effective scroll offset=] is the scroll offset corresponding to the
    first matching condition from the following:
    <div class="switch">

    :   <var>offset</var> is <code>auto</code>
    ::  Either the beginning or the ending of {{source}}'s scroll range in
        {{orientation}} depending on whether the offset is {{start}} or {{end}}.

    :   <var>offset</var> is a <<length-percentage>>
    ::  The distance indicated by the value along {{source}}'s scroll range in
        {{orientation}} as expressed by absolute length, a percentage, or a
        ''calc()'' expression that resolves to a <<length>>.

    </div>

Note: The scroll range of an element is the range defined by its minimum and
maximum scroll offsets which are determined by it [=scrolling box=], [=padding
box=], and [=overflow direction=].

Note: It is valid to provide a length or percentage based offset such that it is
outside the source's scroll range and thus not reachable e.g., '120%'.

#### Element-based Offset #### {#element-based-offset-section}

An <dfn>element-based offset</dfn> is a scroll timeline offset that is declared
in terms of the intersection of the <a>scroll container</a> as specified by
{{source}} and one of its descendents as specified by {{target}}.

An [=element-based offset=] is provided in the {{ElementBasedOffset}} form.

<pre class="idl">
enum Edge { "start", "end" };

dictionary ElementBasedOffset {
  Element target;
  Edge edge = "start";
  double threshold = 0.0;
};
</pre>


<div class=members>

:   <dfn dict-member for=ElementBasedOffset>target</dfn>
::  The target whose intersection with {{source}}'s [=scrolling box=] determines
    the concrete scroll offset.

:   <dfn dict-member for=ElementBasedOffset>edge</dfn>
::  The edge of {{source}}'s [=scrolling box=] in the direction specified by
    the {{orientation}} which the target should intersect with.

:   <dfn dict-member for=ElementBasedOffset>threshold</dfn>
::  A double in the range of [0.0, 1.0] that represent the percentage
    of the target that is expected to be visible in  {{source}}'s [=scrollport=]
    at the intersection offset.

Issue(5203): The range of the <code>threshold</code> member is not currently
checked anywhere.

</div>


The procedure to <dfn>resolve an element-based offset</dfn> given
<var>offset</var> is as follows:

1.  If <em>any</em> of the following are true:

    * {{source}} is null, or
    * {{source}} does not currently have a [=CSS layout box=], or
    * {{source}}'s layout box is not a [=scroll container=].

    The [=effective scroll offset=] is null and abort remaining steps.

1.  Let <var>target</var> be <var>offset</var>'s {{target}}.

1.  If <em>any</em> of the following are true:

    * <var>target</var> is null, or
    * <var>target</var> does not currently have a [=CSS layout box=].

    The [=effective scroll offset=] is null and abort remaining steps.


1.  If <var>target</var> 's nearest [=scroll container=] ancestor
    is not {{source}}
    abort remaining steps
    since the [=effective scroll offset=] is null.

1.  Let <var>container box</var> be the {{source}}'s [=scrollport=].

1.  Let <var>target box</var> be the result of finding
    the rectangular bounding box
    (axis-aligned in {{source}}’s coordinate space)
    of <var>target</var>'s transformed border box.

1.  If <var>offset</var>'s {{edge}} is 'start' then
    let <var>scroll offset</var>
    be the scroll offset at which <var>container box</var>'s start edge is flush
    with the <var>target box</var>'s end edge
    in the axis and direction determined by {{orientation}}.

1.  If <var>offset</var>'s {{edge}} is 'end' then
    let <var>scroll offset</var>
    be the scroll offset at which <var>container box</var>'s end edge is flush
    with the <var>target box</var>'s start edge
    in the axis and direction determined by {{orientation}}.

1.  Let <var>threshold amount</var> be the result of evaluating the following
    expression where <var>target dimension</var> is <var>target box</var>'s dimension in the axis
    determined by {{orientation}}.
    <blockquote>
      <code><var>threshold amount</var> = {{threshold}} &times; <var>target dimension</var></code>
    </blockquote>


1.  Adjust <var>scroll offset</var> by <var>threshold amount</var> as follow:
    <div class="switch">

    :   If <var>offset</var>'s {{edge}} is 'start',
    ::  <var>scroll offset</var> = <var>scroll offset</var> - <var>threshold amount</var>.

    :   Otherwise (<var>offset</var>'s {{edge}} is 'end'),
    ::  <var>scroll offset</var> = <var>scroll offset</var> + <var>threshold amount</var>.

    </div>

1.  Clamp the value of <var>scroll offset</var> to be within the {{source}}'s
     scroll range.

1.  The [=effective scroll offset=] is <var>scroll offset</var>


<div class="note">
Note: With threshold 0.0, the algorithm selects the effective scroll offset such
that the target is adjacent to the [=scrollport=] at the given edge but not yet
visible.
The threshold value allows authors
to control the amount of target that needs to be visible in [=scrollport=].
In particular threshold value 1.0 ensure that target is fully visible
(as long as [=scrollport=] is large enough).

<figure>
<img src="img/example-element-based-threshold.svg" width="600"
alt="Example usage of element-based offset.">
 <figcaption>
  Threshold controls how much of target should be visible in [=scrollport=].
 </figcaption>
</figure>

</div>

<div class="example">
Here is a basic example showing how element-based offsets can be used to declare
an scroll-linked animation that occurs when an element enters the scroller
scrollport and ends once it exits the scrollport.

<figure>
<img src="img/example-element-based.svg" width="600"
alt="Example usage of element-based offset.">
 <figcaption>
  Usage of element-based offsets to create enter/exit triggers.<br>
  The left figure shows the scroller and target being aligned at 'end' edge.<br>
  The right figure shows them being aligned at 'start' edge.
 </figcaption>
</figure>


Note that here we are expecting a typical top to bottom scrolling and thus
consider the entrance to coincide when target's start edge is flushed with
scrollport's <strong>end edge</strong> and viceversa for exit.

<pre class='lang-javascript'>
if (window.matchMedia('(prefers-reduced-motion: no-preference)').matches) {
  const scrollableElement = document.querySelector('#container');
  const image = document.querySelector('#image');

  const timeline = new ScrollTimeline({
    source: scrollableElement,
    start: {target: image, edge: 'end'},
    end: {target: image, edge: 'start'},
  });

  const slideIn = target.animate({
      transform: ['translateX(0)', 'translateX(50vw)'],
      opacity: [0, 1]
    }, {
      timeline:timeline,
      duration: 1000
    }
  );
}
</pre>

The same logic can be done in CSS markup:
<pre class="lang-css">
@media (prefers-reduced-motion: no-preference) {

  @keyframes slide-in {
    from {
      transform: translateX(0);
      opacity: 0;
    }

    to {
      transform: translateX(50vw);
      opacity: 1;
    }
  }

  @scroll-timeline image-in-scrollport {
    source: selector(#container);
    start: selector(#image) end;
    end: selector(#image) start;
  }

  #target {
    animation-name: slide-in;
    animation-duration: 1s;
    animation-timeline: image-in-scrollport;
  }

}
</pre>


</div>

### The effective time range of a {{ScrollTimeline}} ### {#effective-time-range-algorithm}

The <dfn>effective time range</dfn> of a {{ScrollTimeline}} is calculated as
follows:

<div class="switch">

:   If the {{timeRange}} has the value <code>"auto"</code>,
::  The [=effective time range=] is the maximum value of the
    [=target effect end=] of all animations
    directly associated with this timeline.

    If any animation directly associated with the timeline has a
    [=target effect end=] of infinity, the [=effective time range=]
    is zero.

:   Otherwise,
::  The [=effective time range=] is the {{ScrollTimeline}}'s
    {{timeRange}}.

</div>

### The effective scroll range of a {{ScrollTimeline}} ### {#effective-scroll-range-algorithm}

The procedure to calculate <dfn>effective scroll range</dfn> of a
{{ScrollTimeline}} is as follows:

1.  Run the procedure to [=resolve a scroll timeline offset=] for both {{start}}
    and {{end}}.

1.  Calculate [=effective scroll range=] as follow:
    <div class="switch">
    :   If [=effective start offset=] or [=effective end offset=] is null.
    ::  The [=effective scroll range=] is null.

    :   Otherwise
    ::  The [=effective scroll range=] is the result of evaluating the following
        expression:
        <blockquote>
        <code>[=effective end offset=] - [=effective start offset=]</code>
        </blockquote>

    </div>


### The phase of a {{ScrollTimeline}} ### {#phase-algorithm}

The [=phase=] of a {{ScrollTimeline}} is calculated as follows:

1.  If <em>any</em> of the following are true:

    * {{source}} is null, or
    * {{source}} does not currently have a [=CSS layout box=], or
    * {{source}}'s layout box is not a [=scroll container=], or
    * [=effective scroll range=] is null.

    The [=phase=] is [=inactive phase|inactive=] and abort remaining steps.

1.  Let <var>current scroll offset</var> be the current scroll offset of
    {{source}} in the direction specified by {{orientation}}.

1.  The [=phase=] is the result corresponding to the first matching condition
    from below:

<div class="switch">

:   If <var>current scroll offset</var> is less than [=effective start offset=]:
::  The [=phase=] is [=before phase|before=]

:   If <var>current scroll offset</var> is greater than or equal to [=effective
    end offset=] <em>and</em> [=effective end offset=] is less than the maximum
    scroll offset of {{source}} in {{orientation}}:

::  The [=phase=] is [=after phase|after=]

Note: In web animations, in general ranges are normally exclusive of their end
point. But there is an exception here for the scroll timeline active range as it
may in some cases be inclusive of its end. In particular if the timeline end
offset is the maximum scroll offset we include it in active range because it is
not possible for user to scroll passed this point and not including this value
in the active range would leave to animations that would not be active at the
very last scroll position.

:   Otherwise,
::  The [=phase=] is [=active phase|active=].

</div>

### The current time of a {{ScrollTimeline}} ### {#current-time-algorithm}

The [=current time=] of a {{ScrollTimeline}} is calculated as follows:

1.  If <em>any</em> of the following are true:

    * {{source}} is null, or
    * {{source}} does not currently have a [=CSS layout box=], or
    * {{source}}'s layout box is not a [=scroll container=], or
    * [=effective scroll range=] is null.

    The [=current time=] is an unresolved time value and abort remaining steps.

1.  Let <var>current scroll offset</var> be the current scroll offset of
    {{source}} in the direction specified by {{orientation}}.

1.  The [=current time=] is the result corresponding to the first matching
    condition from below:

<div class="switch">

:   If <var>current scroll offset</var> is less than [=effective start offset=]:
::  The [=current time=] is 0.

:   If <var>current scroll offset</var> is greater than or equal to [=effective
    end offset=]:
::  The [=current time=] is the [=effective time range=].

:   Otherwise,
::  The [=current time=] is the result of evaluating the following expression:

    <blockquote>
      <code>(<var>current scroll offset</var> - [=effective start offset=]) / [=effective scroll range=] &times; [=effective time range=]</code>
    </blockquote>

</div>

Note: To be considered active a scroll timeline requires its [=effective start
offset=] and its [=effective end offset=] to be non-null. This means that for
example if one uses an element-based offset whose {{target}} is not a descendant
of the scroll timeline {{source}}, the timeline remains inactive.

## The '@scroll-timeline' at-rule ## {#scroll-timeline-at-rule}

[=Scroll Timelines=] are specified in CSS using the <dfn>@scroll-timeline</dfn>
at-rule, defined as follows:

<pre>
  @scroll-timeline = @scroll-timeline <<timeline-name>> { <<declaration-list>> }

</pre>

An ''@scroll-timeline'' rule has a name given by the <<custom-ident>> or <<string>> in
its prelude. The two syntaxes are equivalent in functionality; the name is the
value of the ident or string. As normal for <<custom-ident>>s and <<string>>s,
the names are fully case-sensitive; two names are equal only if they are
codepoint-by-codepoint equal. The <<custom-ident>> additionally excludes the
none keyword.

Once specified, a scroll timeline may be associated with a CSS Animation
[[CSS3-ANIMATIONS]] by using the 'animation-timeline' property.

The <<declaration-list>> inside of ''@scroll-timeline'' rule can only contain the
descriptors defined in this section.

An ''@scroll-timeline'' rule is invalid if it occurs in a stylesheet inside of a
[=shadow tree=], and must be ignored.

Issue(5167): This will likely change in the future.

### Scroll Timeline descriptors ### {#scroll-timeline-descriptors}


<pre class='descdef'>
  Name: source
  For: @scroll-timeline
  Value: selector( <<id-selector>> ) | auto | none
  Initial: auto
</pre>

'source' descriptor determines the scroll timeline's {{source}}.

The value of {{source}} is the result corresponding to the first matching
condition from the following:

<div class="switch">

:   If 'source' is a 'selector()'
::  The [=scroll container=] identified by the <<id-selector>>.

:   If 'source' is <code>auto</code>
::  The {{scrollingElement}} of the {{Document}} <a lt="document associated with
    a window">associated</a> with the {{Window}} that is the
    <a>current global object</a>.

:   Otherwise ('source' is <code>none</code>)
::  null.

</div>

Issue(4338): Consider choosing animation target's nearest scrollable ancestor
instead of document's scrolling Element for <code>auto</code>.

<pre class='descdef'>
  Name: orientation
  For: @scroll-timeline
  Value: auto | block | inline | horizontal | vertical
  Initial: auto
</pre>

'orientation' descriptor determines the scroll timeline's {{orientation}}.


<pre class='descdef'>
  Name: start
  For: @scroll-timeline
  Value: <<scroll-timeline-offset>>
  Initial: auto
</pre>

'start' descriptor determines the scroll timeline's {{start}}.

[=Scroll timeline offsets=] in CSS are represented by the
<<scroll-timeline-offset>> type:

<pre>
<dfn>&lt;scroll-timeline-offset></dfn> = auto | <<length-percentage>> | <<element-offset>>
<dfn>&lt;element-offset></dfn> = selector( <<id-selector>> ) [<<element-offset-edge>> || <<number>>]?
<dfn>&lt;element-offset-edge></dfn> = start | end
</pre>

The offset type depends on the value of <<scroll-timeline-offset>> per
following:
<div class="switch">
:   If value is "auto" or of type <<length-percentage>>
::  The [=scroll timeline offset=] is a [=container-based offset=] with the same
    value.

:   If value is of type <<element-offset>>
::  The [=scroll timeline offset=] is an [=element-based offset=] with the
    following member values:
      *  {{ElementBasedOffset/target}} is the element identified by
          <<id-selector>>.
      * {{ElementBasedOffset/edge}} is the optional value of
        <<element-offset-edge>>. If not provided it defaults to "start".
      * {{ElementBasedOffset/threshold}} is the optional value <<number>>. If
        not provided it defaults to 0.

</div>

<pre class='descdef'>
  Name: end
  For: @scroll-timeline
  Value: <<scroll-timeline-offset>>
  Initial: auto
</pre>

'end' descriptor determines the scroll timeline's {{end}}.


<pre class='descdef'>
  Name: time-range
  For: @scroll-timeline
  Value: auto | <<time>>
  Initial: auto
</pre>

'time-range' descriptor determines the scroll timeline's {{timeRange}}.

</div>  <!-- link-for-hint="ScrollTimeline" -->

### The <dfn interface>CSSScrollTimelineRule</dfn> Interface ### {#the-css-scroll-timeline-rule-interface}

<pre class='idl' export>
[Exposed=Window]
interface CSSScrollTimelineRule : CSSRule {
    readonly attribute CSSOMString name;
    readonly attribute CSSOMString source;
    readonly attribute CSSOMString orientation;
    readonly attribute CSSOMString start;
    readonly attribute CSSOMString end;
    readonly attribute CSSOMString timeRange;
};
</pre>

<dl dfn-for=CSSScrollTimelineRule dfn-type=attribute>
  <dt><dfn>name</dfn></dt>
  <dd>
    The name associated with the ''@scroll-timeline'' rule.
  </dd>

  <dt><dfn>source</dfn></dt>
  <dd>
    The 'source' descriptor associated with the ''@scroll-timeline'', or "auto"
    if not specified.
  </dd>

  <dt><dfn>orientation</dfn></dt>
  <dd>
    The 'orientation' descriptor associated with the ''@scroll-timeline'', or "auto" if not specified.
  </dd>

  <dt><dfn>start</dfn></dt>
  <dd>
    The 'start' descriptor associated with the ''@scroll-timeline'', or "auto" if not specified.
  </dd>

  <dt><dfn>end</dfn></dt>
  <dd>
    The 'end' descriptor associated with the ''@scroll-timeline'', or "auto" if not specified.
  </dd>

  <dt><dfn>timeRange</dfn></dt>
  <dd>
    The 'time-range' descriptor associated with the ''@scroll-timeline'', or "auto" if not specified.
  </dd>
</dl>

## Examples ## {#timeline-examples}

<div class="example">
  Draw a reading progress bar along the top of the page as the user scrolls
  <pre class="lang-css">
    #progress {
      position: fixed;
      top: 0;
      width: 0;
      height: 2px;
      background-color: red;
    }
  </pre>
  <pre class="lang-javascript">
    if (window.matchMedia('(prefers-reduced-motion: no-preference)').matches) {
      let progress = document.getElementById("progress");
      let effect = new KeyframeEffect(
        progress,
        [
          { width: "0vw" },
          { width: "100vw" }
        ],
        {
          duration: 1000,
          easing: "linear",
          fill: "forwards"
        });
      let timeline = new ScrollTimeline({
        scrollSource: document.documentElement,
        orientation: "vertical",
      });
      let animation = new Animation(effect, timeline);
      animation.play();
    }
  </pre>
</div>

<div class="example">
  The same thing with CSS, using 'animation-timeline'
  <pre class="lang-css">
    @media (prefers-reduced-motion: no-preference) {

      @scroll-timeline progress {
        /* Assume the HTML element has id 'root' */
        source: selector(#root);
        orientation: vertical;
      }

      @keyframes progress {
        from {
          width: 0vw;
        }
        to {
          width: 100vw;
        }
      }

      #progress {
        position: fixed;
        top: 0;
        width: 0;
        height: 2px;
        background-color: red;
        /* This name is used to select both the keyframes and the
           scroll-timeline at-rules. */
        animation-name: progress;
        animation-duration: 1s;
        animation-fill-mode: forwards;
        animation-timing-function: linear;
      }

    }
  </pre>
</div>

# Avoiding cycles with layout # {#avoiding-cycles}

The ability for scrolling to drive the progress of an animation, gives rise to
the possibility of <dfn>layout cycles</dfn>, where a change to a scroll offset
causes an animation's effect to update, which in turn causes a new change to the
scroll offset.

To avoid such [=layout cycles=], animations with a {{ScrollTimeline}} are
sampled once per frame, after scrolling in response to input events has taken
place, but before {{requestAnimationFrame()}} callbacks are run. If the sampling
of such an animation causes a change to a scroll offset, the animation will not
be re-sampled to reflect the new offset until the next frame.

The implication of this is that in some situations, in a given frame, the
rendered scroll offset of a scroll container may not be consistent with the state
of an animation driven by scrolling that scroll container. However, this will
only occur in situations where the animation's effect changes the scroll offset
of that same scroll container (in other words, in situations where the animation's
author is asking for trouble). In normal situations, including - importantly -
when scrolling happens in response to input events, the rendered scroll offset
and the state of scroll-driven animations will be consistent in each frame.

User agents that composite frames asynchronously with respect to layout and/or
script may, at their discretion, sample scroll-driven animations once per
<em>composited</em> frame, rather than (or in addition to) once per full layout
cycle. Again, if sampling such an animation causes a change to a scroll offset,
the animation will not be re-sampled to reflect the new offset until the next
frame.

Nothing in this section is intended to require that scrolling block on layout
or script. If a user agent normally composites frames where scrolling has
occurred but the consequences of scrolling have not been fully propagated in
layout or script (for example, <code>scroll</code> event listeners have not yet
run), the user agent may likewise choose not to sample scroll-driven animations
for that composited frame. In such cases, the rendered scroll offset and the
state of a scroll-driven animation may be inconsistent in the composited frame.


<h2 id="appendix-a-considerations-for-security-and-privacy">Appendix A. Considerations for Security and Privacy</h2>

This appendix is <em>informative</em>.

There are no known security or privacy impacts of this feature.

The W3C TAG is developing a
<a href="https://www.w3.org/TR/security-privacy-questionnaire/">Self-Review Questionnaire: Security and Privacy</a>
for editors of specifications to informatively answer.

Per the <a href="https://www.w3.org/TR/security-privacy-questionnaire/#questions">Questions to Consider</a>

<ol>
<li>Does this specification deal with personally-identifiable information?
<p>No.</p>
</li>

<li>Does this specification deal with high-value data?
<p>No.</p>
</li>

<li>Does this specification introduce new state for an origin that persists across browsing sessions?
<p>No.</p>
</li>

<li>Does this specification expose persistent, cross-origin state to the web?
<p>No.</p>
</li>

<li>Does this specification expose any other data to an origin that it doesn’t currently have access to?
<p>No.</p>
</li>

<li>Does this specification enable new script execution/loading mechanisms?
<p>No.</p>
</li>

<li>Does this specification allow an origin access to a user’s location?
<p>No.</p>
</li>

<li>Does this specification allow an origin access to sensors on a user’s device?
<p>No.</p>
</li>

<li>Does this specification allow an origin access to aspects of a user’s local computing environment?
<p>No.</p>
</li>

<li>Does this specification allow an origin access to other devices?
<p>No.</p>
</li>

<li>Does this specification allow an origin some measure of control over a user agent’s native UI?
<p>No.</p>
</li>

<li>Does this specification expose temporary identifiers to the web?
<p>No.</p>
</li>

<li>Does this specification distinguish between behavior in first-party and third-party contexts?
<p>No.</p>
</li>

<li>How should this specification work in the context of a user agent’s "incognito" mode?
<p>No differently. The website should not be able to determine that the user is
in an "incognito" mode using scroll-linked animations.</p>
</li>

<li>Does this specification persist data to a user’s local device?
<p>No.</p>
</li>

<li>Does this specification have a "Security Considerations" and "Privacy Considerations" section?
<p>Yes.</p>
</li>

<li>Does this specification allow downgrading default security characteristics?
<p>No.</p>
</li>
</ol>