Scroll-linked Animations

1. Introduction

This specification defines mechanisms for driving the progress of an animation based on the scroll progress of a scroll container. These scroll-driven animations use a timeline based on scroll position, rather than one based on clock time. Animations are linked to such a timeline using the CSS animation-timeline property or the Web Animations API. [WEB-ANIMATIONS-1]

There are two types of scroll-driven timelines:

• scroll progress timelines

• view progress timelines

1.1. Relationship to other specifications

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 progress timeline.

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

The behavior of the CSS properties is described in terms of the programming interfaces. User agents that do not support scripting may still conform to this specification by implementing the CSS features to behave as if the underlying programming interfaces were in place.

1.2. Relationship to asynchronous 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.

1.3. Value Definitions

This specification follows the CSS property definition conventions from [CSS2] using the value definition syntax from [CSS-VALUES-3]. Value types not defined in this specification are defined in CSS Values & 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 CSS-wide keywords as their property value. For readability they have not been repeated explicitly.

2. Scroll Progress Timelines

Scroll progress timelines are timelines linked to progress in the scroll position of a scroll container along a particular axis. The startmost scroll position represents 0% progress and the endmost scroll position represents 100% progress. If the 0% position and 100% position coincide (i.e. the scroll container has no overflow to scroll), the timeline is inactive.

Scroll progress timelines can be referenced in animation-timeline anonymously using the scroll() functional notation or by name (see § 4 Named Timeline Scoping) after declaring them using the scroll-timeline properties. In the Web Animations API, they can be represented anonymously by a ScrollTimeline object.

2.1. Anonymous Scroll Progress Timelines

2.1.1. The scroll() notation

The scroll() functional notation can be used as a value of animation-timeline and specifies a scroll progress timeline. Its syntax is

scroll() = scroll( <axis>? <scroller>? )
<axis> = block | inline | vertical | horizontal
<scroller> = root | nearest | <custom-ident>

By default, scroll() references the block axis of the nearest ancestor scroll container. Its arguments modify this lookup as follows:

block

Specifies to use the measure of progress along the block axis of the scroll container. (Default.)

inline

Specifies to use the measure of progress along the inline axis of the scroll container.

vertical

Specifies to use the measure of progress along the vertical axis of the scroll container.

horizontal

Specifies to use the measure of progress along the horizontal axis of the scroll container.

nearest

Specifies to use the nearest ancestor scroll container. (Default.)

root

Specifies to use the document viewport as the scroll container.

<custom-ident>

Specifies to use the nearest ancestor scroll container that has the specified container-name. [CSS-CONTAIN-3] If none exist, the document viewport is used.

2.1.2. The ScrollTimeline Interface

enum ScrollAxis {
  "block",
  "inline",
  "horizontal",
  "vertical"
};

dictionary ScrollTimelineOptions {
  Element? source;
  ScrollAxis axis = "block";
};

[Exposed=Window]
interface ScrollTimeline : AnimationTimeline {
  constructor(optional ScrollTimelineOptions options = {});
  readonly attribute Element? source;
  readonly attribute ScrollAxis axis;
};

A ScrollTimeline is an AnimationTimeline that represents a scroll progress timeline. It can be passed to the Animation constructor or the animate() method to link the animation to a scroll progress timeline.

source, of type Element, readonly, nullable

The scroll container element whose scroll position drives the progress of the timeline.

axis, of type ScrollAxis, readonly

The axis of scrolling that drives the progress of the timeline. See value definitions for <axis>, above.

Inherited attributes:

currentTime (inherited from AnimationTimeline)

Represents the scroll progress of the scroll container as a percentage CSSUnitValue, with 0% representing its startmost scroll position (in the writing mode of the scroll container). Null when the timeline is inactive.

While 0% will usually represent the scroll container’s initial scroll position, it might not depending on its content distribution. See CSS Box Alignment 3 § 5.3 Overflow and Scroll Positions. Is this what we want?

Add a note about whether currentTime can be negative or > 100%.

ScrollTimeline(options)

Creates a new ScrollTimeline object using the following procedure:

1. Let timeline be the new ScrollTimeline object.

2. Set the source of timeline to:

   If the source member of options is present and not null,

   The source member of options.

   Otherwise,

   The scrollingElement of the Document associated with the Window that is the current global object.

3. Set the axis property of timeline to the corresponding value from options.

If the source of a ScrollTimeline is an element whose principal box does not exist or is not a scroll container, then the ScrollTimeline is inactive. It is otherwise in the active timeline state.

A ScrollTimeline’s duration is 100%.

2.2. Named Scroll Progress Timelines

Scroll timelines can also be defined on the scroll container itself, and then referenced by name. See § 4 Named Timeline Scoping.

2.2.1. Naming a Scroll Progress Timeline: the scroll-timeline-name property

Specifies a name for the scroll progress timeline associated with this scroll container. The axis for this timeline is given by scroll-timeline-axis.

2.2.2. Axis of a Scroll Progress Timeline: the scroll-timeline-axis property

Specifies an axis for the scroll progress timeline associated with this scroll container. The name for this timeline is given by scroll-timeline-name.

Values are as defined for scroll().

2.2.3. Scroll Timeline Shorthand: the scroll-timeline shorthand

This property is a shorthand for setting scroll-timeline-name and scroll-timeline-axis in a single declaration.

3. View Progress Timelines

Often animations are desired to start and end during the portion of the scroll progress timeline that a particular element (the view progress subject element) is in view within the scrollport. View progress timelines are segments of a scroll progress timeline that are scoped to the scroll positions in which the associated element’s principal box intersects its nearest ancestor scrollport. The startmost such scroll position represents 0% progress and the endmost such scroll position represents 100% progress.

View progress timelines can be referenced in animation-timeline by name (see § 4 Named Timeline Scoping) after declaring them using the view-timeline properties on the view progress subject. In the Web Animations API, they can be represented anonymously by a ViewTimeline object.

3.1. Anonymous View Progress Timelines

3.1.1. The ViewTimeline Interface

dictionary ViewTimelineOptions {
  Element subject;
  ScrollAxis axis = "block";
};

[Exposed=Window]
interface ViewTimeline : ScrollTimeline {
  constructor(optional ViewTimelineOptions options = {});
  readonly attribute Element subject;
  readonly attribute CSSNumericValue startOffset;
  readonly attribute CSSNumericValue endOffset;
};

A ViewTimeline is an AnimationTimeline that specifies a view progress timeline. It can be passed to the Animation constructor or the animate() method to link the animation to a view progress timeline.

subject, of type Element, readonly

The element whose principal box’s visibility in the scrollport defines the progress of the timeline.

startOffset, of type CSSNumericValue, readonly

Represents the starting (0% progress) scroll position of the view progress timeline as a length offset (in px) from the scroll origin. Null when the timeline is inactive.

endOffset, of type CSSNumericValue, readonly

Represents the ending (100% progress) scroll position of the view progress timeline as a length offset (in px) from the scroll origin. Null when the timeline is inactive.

Note: The value of startOffset can be greater than endOffset, for example in the horizontal axis in a right-to-left (rtl) writing mode.

This makes the offsets compatible with the way scrollLeft and scrollTop work, which go negative from zero in RTL scroll containers, is this how we want it to work here?

Inherited attributes:

source (inherited from ScrollTimeline)

The nearest ancestor of the subject whose principal box establishes a scroll container, whose scroll position drives the progress of the timeline.

axis (inherited from ScrollTimeline)

Specifies the axis of scrolling that drives the progress of the timeline. See <axis>, above.

currentTime (inherited from AnimationTimeline)

Represents the current progress of the view progress timeline as a percentage CSSUnitValue representing its scroll container’s scroll progress at that position. Null when the timeline is inactive.

ViewTimeline(options)

Creates a new ViewTimeline object using the following procedure:

1. Let timeline be the new ViewTimeline object.

2. Set the subject and axis properties of timeline to the corresponding values from options.

3. Set the source of timeline to the subject’s nearest ancestor scroll container element.

If the source or subject of a ViewTimeline is an element whose principal box does not exist, then the ViewTimeline is inactive. It is otherwise in the active timeline state.

Figure out how to incorporate fit/inset abilities.

3.2. Named View Progress Timelines

View timelines can also be defined declaratively and then referenced by name. See § 4 Named Timeline Scoping.

3.2.1. Naming a View Progress Timeline: the view-timeline-name property

Specifies names for any view progress timelines associated with this element’s principal box.

Note: The number of names listed here determines the number of view progress timelines associated with this element.

3.2.2. Axis of a View Progress Timeline: the view-timeline-axis property

Specifies an axis for each named view progress timeline associated with this scroll container.

If view-timeline-name has more names than view-timeline-axis has specified axes, the excess timelines use the last view-timeline-axis value. If view-timeline-name has fewer names than view-timeline-axis has specified axes, the used view-timeline-axis list is truncated.

3.2.3. Inset of a View Progress Timeline: the view-timeline-inset property

Specifies an inset (positive) or outset (negative) adjustment of the scrollport when determining whether the box is in view when setting the bounds of a view progress timeline. The resulting rectangle is the view progress rectangle.

auto

Indicates to use the value of scroll-padding.

<length-percentage>

Like scroll-padding, defines an inward offset from the corresponding edge of the scrollport.

The view-timeline-inset property assigns its values to each side exactly as the margin property does.

Should the initial value be zero or auto?

Do we need all the longhands? Seems like overkill...

3.2.4. View Timeline Shorthand: the view-timeline shorthand

This property is a shorthand for setting view-timeline-name and view-timeline-axis in a single declaration. It does not set view-timeline-inset.

Should it reset view-timeline-inset also?

4. Named Timeline Scoping

A named scroll progress timeline or view progress timeline is referenceable in animation-timeline by:

• the declaring element itself

• that element’s descendants

• that element’s following siblings and their descendants

If multiple elements have declared the same timeline name, the matching timeline is the one declared on the nearest element in tree order, which considers siblings closer than parents. In case of a name conflict on the same element, scroll progress timelines take precedence over view progress timelines.

Do we want to expand this scope to preceding siblings and/or distant cousins?

5. Avoiding cycles with layout

The ability for scrolling to drive the progress of an animation, gives rise to the possibility of layout cycles, 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 scroll progress timeline 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 might 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 composited 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, scroll 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.