Scroll-linked Animations

W3C First Public Working Draft,

More details about this document
This version:
https://www.w3.org/TR/2022/WD-scroll-animations-1-1-20221118/
Latest published version:
https://www.w3.org/TR/scroll-animations-1/
Editor's Draft:
https://drafts.csswg.org/scroll-animations-1/
History:
https://www.w3.org/standards/history/scroll-animations-1-1
Feedback:
CSSWG Issues Repository
Inline In Spec
Editors:
(Invited Expert)
(Mozilla)
(Apple)
(Microsoft)
Elika J. Etemad / fantasai (Invited Expert)
Robert Flack (Google)
Former Editors:
(Google)
Mantaroh Yoshinaga
(Google)
Suggest an Edit for this Spec:
GitHub Editor

Abstract

Defines an API and markup for creating animations that are tied to the scroll offset of a scroll container.

CSS is a language for describing the rendering of structured documents (such as HTML and XML) on screen, on paper, etc.

Status of this document

This section describes the status of this document at the time of its publication. 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 CSS Working Group as a First Public Working Draft using the Recommendation track. Publication as a First Public Working Draft does not imply endorsement by W3C and its Members.

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.

Please send feedback by filing issues in GitHub (preferred), including the spec code “scroll-animations-1” in the title, like this: “[scroll-animations-1] …summary of comment…”. All issues and comments are archived. Alternately, feedback can be sent to the (archived) public mailing list www-style@w3.org.

This document is governed by the 2 November 2021 W3C Process Document.

This document was produced by a group operating under the 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.

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. This module provides both an imperative API building on the Web Animations API as well as a declarative API building on CSS Animations. [WEB-ANIMATIONS-1]

There are two types of scroll-driven timelines:

Note: Scroll-driven animations, whose progress is linked to the scroll position, are distinct from scroll-triggered animations, which are triggered by a scroll position, but whose progress is driven by time.

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 [CSS-ANIMATIONS-1].

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( [ <scroller> || <axis> ]? )
<axis> = block | inline | vertical | horizontal
<scroller> = root | nearest

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.

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, or if there is no scrollable overflow, then the ScrollTimeline is inactive.

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

Name: scroll-timeline-name
Value: none | <custom-ident>
Initial: none
Applies to: scroll containers
Inherited: no
Percentages: n/a
Computed value: the specified keyword
Canonical order: per grammar
Animation type: not animatable

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

Name: scroll-timeline-axis
Value: block | inline | vertical | horizontal
Initial: block
Applies to: scroll containers
Inherited: no
Percentages: n/a
Computed value: the specified keyword
Canonical order: per grammar
Animation type: not animatable

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

Name: scroll-timeline
Value: <'scroll-timeline-name'> || <'scroll-timeline-axis'>
Initial: see individual properties
Applies to: scroll containers
Inherited: no
Percentages: see individual properties
Computed value: see individual properties
Animation type: not animatable
Canonical order: per grammar

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 any part of the associated element’s principal box intersects its nearest ancestor scrollport (or more precisely, the relevant view progress visibility range of that scrollport). The startmost such scroll position represents 0% progress and the endmost such scroll position represents 100% progress.

Note: The 0% and 100% scroll positions are not always reachable, e.g. if the box is positioned at the start edge of the scrollable overflow rectangle, it might not be possible to scroll to < 32% 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. View Progress Timeline Ranges

View progress timelines define the following named timeline ranges:

cover
Represents the full range of the view progress timeline:
contain
Represents the range during which the principal box is either fully contained by, or fully covers, its view progress visibility range within the scrollport.
entry
Represents the range during which the principal box is entering the view progress visibility range.
  • 0% is equivalent to 0% of the cover range.

  • 100% is equivalent to 0% of the contain range.

Should this be entry or enter?

exit
Represents the range during which the principal box is exiting the view progress visibility range.
  • 0% is equivalent to 100% of the contain range.

  • 100% is equivalent to 100% of the cover range.

Insert diagrams.

In all cases, the writing mode used to resolve the start and end sides is the writing mode of the relevant scroll container.

3.2. Anonymous View Progress Timelines

3.2.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, or if its nearest ancestor scroll container has no scrollable overflow, then the ViewTimeline is inactive.

Figure out how to incorporate fit/inset abilities.

3.3. Named View Progress Timelines

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

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

Name: view-timeline-name
Value: none | <custom-ident>#
Initial: none
Applies to: all elements
Inherited: no
Percentages: n/a
Computed value: the keyword none or a list of <custom-ident>s
Canonical order: per grammar
Animation type: not animatable

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.3.2. Axis of a View Progress Timeline: the view-timeline-axis property

Name: view-timeline-axis
Value: [ block | inline | vertical | horizontal ]#
Initial: block
Applies to: all elements
Inherited: no
Percentages: n/a
Computed value: a list of the keywords specified
Canonical order: per grammar
Animation type: not animatable

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.3.3. Inset of a View Progress Timeline: the view-timeline-inset property

Name: view-timeline-inset
Value: [ [ auto | <length-percentage> ]{1,2} ]#
Initial: 0
Applies to: all elements
Inherited: no
Percentages: relative to the corresponding dimension of the relevant scrollport
Computed value: a list consisting of two-value pairs representing the start and end insets each as either the keyword auto or a computed <length-percentage> value
Canonical order: per grammar
Animation type: by computed value type

Specifies an inset (positive) or outset (negative) adjustment of the scrollport when determining whether the box is in view when setting the bounds of the corresponding view progress timeline. The first value represents the start inset in the relevant axis; the second value represents the end inset. If the second value is omitted, it is set to the first. The resulting range of the scrollport is the view progress visibility range.

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.

If view-timeline-name has more names than view-timeline-inset has specified inset pairs, the excess timelines use the last view-timeline-inset pair. If view-timeline-name has fewer names than view-timeline-inset has specified inset pairs the used view-timeline-inset list is truncated.

3.3.4. View Timeline Shorthand: the view-timeline shorthand

Name: view-timeline
Value: [ <'view-timeline-name'> || <'view-timeline-axis'> ]#
Initial: see individual properties
Applies to: all elements
Inherited: see individual properties
Percentages: see individual properties
Computed value: see individual properties
Animation type: see individual properties
Canonical order: per grammar

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:

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.

Note: Like most operations in CSS besides selector matching, timeline scoping occurs over the flattened element tree.

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.

Appendix A: Named Timeline Ranges

This section should move to CSS-ANIMATIONS-2 and WEB-ANIMATIONS-2.

This specification introduces the concept of named timeline ranges to CSS Animations and Web Animations.

A named timeline range is a named segment of an animation timeline. The start of the segment is represented as 0% progress through the range; the end of the segment is represented as 100% progress through the range. Multiple named timeline ranges can be attached to a given timeline, and multiple such ranges can overlap. For example, the contain range of a view progress timeline overlaps with its cover range. Named timeline ranges are represented by the <timeline-range-name> value type, which indicates a CSS identifier representing one of the predefined named timeline ranges.

Note: In this specification, named timeline ranges must be defined to exist by a specification such as [SCROLL-ANIMATIONS-1]. A future level may introduce APIs for authors to declare their own custom named timeline ranges.

Named Timeline Range Keyframe Selectors

Named timeline range names and percentages can be used to attach keyframes to specific progress points within the named timeline range. The CSS @keyframes rule is extended thus:

<keyframe-selector> = from | to | <percentage> | <timeline-range-name> <percentage>

where <timeline-range-name> is the CSS identifier that represents a chosen predefined named timeline range, and the <percentage> after it represents the percentage progress between the start and end of that named timeline range.

Keyframes are attached to the specified point in the timeline. If the timeline does not have a corresponding named timeline range, then any keyframes attached to points on that named timeline range are ignored.

Attaching Animations to Timeline Ranges

A set of animation keyframes can be attached in reference to named timeline ranges by adjusting the duration of the animation.

Name: animation-delay, animation-range
Value: [ <'animation-delay-start'> <'animation-delay-end'>? | <timeline-range-name> ]#
Initial: see individual properties
Applies to: see individual properties
Inherited: see individual properties
Percentages: see individual properties
Computed value: see individual properties
Animation type: see individual properties
Canonical order: per grammar

The animation-delay and animation-range properties are both shorthands that set animation-delay-start and animation-delay-end together in a single declaration. If the <'animation-delay-end'> value is omitted, it is set to zero. If a <timeline-range-name> alone is specified, animation-delay-start is set to that name plus 0% and animation-delay-end is set to that name plus 100%.

Name: animation-delay-start
Value: [ <time> | <timeline-range-name> <percentage> ]#
Initial: 0s
Applies to: all elements
Inherited: no
Percentages: relative to the specified named timeline range
Computed value: list, each item either a duration or a timeline range and progress percentage
Canonical order: per grammar
Animatable: no

Defines a delay between the start of the animation and when it begins executing (i.e. when keyframes attached to 0% progress are mapped).

<time>
Defines the delay as a duration. See [CSS-ANIMATIONS-1].
<timeline-range-name> <percentage>
Calculates the delay as the difference between the start of the animation and the specified point on the timeline.
Name: animation-delay-end
Value: [ <time> | <timeline-range-name> <percentage> ]
Initial: 0s
Applies to: all elements
Inherited: no
Percentages: relative to the specified named timeline range
Computed value: list, each item either a duration or a timeline range and progress percentage
Canonical order: per grammar
Animatable: no

Defines a delay between the end of the animation and when it ends executing (i.e. when keyframes attached to 100% progress are mapped). Values are as for animation-delay-start, but calculating backwards from the end, i.e. a 2s delay effectively shortens the animation duration, whereas -2s lengthens it.

Reporting Timeline Range Progress: the getTime() method

Progress through named ranges is exposed on the AnimationTimeline object by the getCurrentTime() method:

[Exposed=Window]
interface AnimationTimeline {
  readonly attribute CSSNumberish? currentTime;
  CSSNumericValue? getCurrentTime(optional CSSOMString rangeName);
};
The getCurrentTime(optional rangeName) method steps are:
  1. If this is an inactive timeline, return null.

  2. If rangeName is provided:

    1. If rangeName is a valid named timeline range on this, let progress be the current progress through that range, expressed as a percentage value between 0 and 100.

      Create a new unit value from (progress, "percent") and return it.

    2. Otherwise, return null.

  3. Let current time be the value of this’s currentTime internal slot.

    Create a new unit value from (current time, "ms") and return it.

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.

Advisements are normative sections styled to evoke special attention and are set apart from other normative text with <strong class="advisement">, like this: UAs MUST provide an accessible alternative.

Conformance classes

Conformance to this specification is defined for three conformance classes:

style sheet
A CSS style sheet.
renderer
A UA that interprets the semantics of a style sheet and renders documents that use them.
authoring tool
A UA that writes a style sheet.

A style sheet is conformant to this specification if all of its statements that use syntax defined in this module are valid according to the generic CSS grammar and the individual grammars of each feature defined in this module.

A renderer is conformant to this specification if, in addition to interpreting the style sheet as defined by the appropriate specifications, it supports all the features defined by this specification by parsing them correctly and rendering the document accordingly. However, the inability of a UA to correctly render a document due to limitations of the device does not make the UA non-conformant. (For example, a UA is not required to render color on a monochrome monitor.)

An authoring tool is conformant to this specification if it writes style sheets that are syntactically correct according to the generic CSS grammar and the individual grammars of each feature in this module, and meet all other conformance requirements of style sheets as described in this module.

Partial implementations

So that authors can exploit the forward-compatible parsing rules to assign fallback values, CSS renderers must treat as invalid (and ignore as appropriate) any at-rules, properties, property values, keywords, and other syntactic constructs for which they have no usable level of support. In particular, user agents must not selectively ignore unsupported component values and honor supported values in a single multi-value property declaration: if any value is considered invalid (as unsupported values must be), CSS requires that the entire declaration be ignored.

Implementations of Unstable and Proprietary Features

To avoid clashes with future stable CSS features, the CSSWG recommends following best practices for the implementation of unstable features and proprietary extensions to CSS.

Non-experimental implementations

Once a specification reaches the Candidate Recommendation stage, non-experimental implementations are possible, and implementors should release an unprefixed implementation of any CR-level feature they can demonstrate to be correctly implemented according to spec.

To establish and maintain the interoperability of CSS across implementations, the CSS Working Group requests that non-experimental CSS renderers submit an implementation report (and, if necessary, the testcases used for that implementation report) to the W3C before releasing an unprefixed implementation of any CSS features. Testcases submitted to W3C are subject to review and correction by the CSS Working Group.

Further information on submitting testcases and implementation reports can be found from on the CSS Working Group’s website at https://www.w3.org/Style/CSS/Test/. Questions should be directed to the public-css-testsuite@w3.org mailing list.

Index

Terms defined by this specification

Terms defined by reference

References

Normative References

[CSS-ALIGN-3]
Elika Etemad; Tab Atkins Jr.. CSS Box Alignment Module Level 3. 24 December 2021. WD. URL: https://www.w3.org/TR/css-align-3/
[CSS-ANIMATIONS-1]
Dean Jackson; et al. CSS Animations Level 1. 11 October 2018. WD. URL: https://www.w3.org/TR/css-animations-1/
[CSS-ANIMATIONS-2]
CSS Animations Module Level 2 URL: https://drafts.csswg.org/css-animations-2/
[CSS-BOX-4]
Elika Etemad. CSS Box Model Module Level 4. 3 November 2022. WD. URL: https://www.w3.org/TR/css-box-4/
[CSS-CASCADE-5]
Elika Etemad; Miriam Suzanne; Tab Atkins Jr.. CSS Cascading and Inheritance Level 5. 13 January 2022. CR. URL: https://www.w3.org/TR/css-cascade-5/
[CSS-DISPLAY-3]
Tab Atkins Jr.; Elika Etemad. CSS Display Module Level 3. 18 November 2022. CR. URL: https://www.w3.org/TR/css-display-3/
[CSS-OVERFLOW-3]
David Baron; Elika Etemad; Florian Rivoal. CSS Overflow Module Level 3. 23 December 2021. WD. URL: https://www.w3.org/TR/css-overflow-3/
[CSS-SCROLL-SNAP-1]
Matt Rakow; et al. CSS Scroll Snap Module Level 1. 11 March 2021. CR. URL: https://www.w3.org/TR/css-scroll-snap-1/
[CSS-TYPED-OM-1]
Shane Stephens; Tab Atkins Jr.; Naina Raisinghani. CSS Typed OM Level 1. 10 April 2018. WD. URL: https://www.w3.org/TR/css-typed-om-1/
[CSS-VALUES-3]
Tab Atkins Jr.; Elika Etemad. CSS Values and Units Module Level 3. 6 June 2019. CR. URL: https://www.w3.org/TR/css-values-3/
[CSS-VALUES-4]
Tab Atkins Jr.; Elika Etemad. CSS Values and Units Module Level 4. 19 October 2022. WD. URL: https://www.w3.org/TR/css-values-4/
[CSS-WRITING-MODES-4]
Elika Etemad; Koji Ishii. CSS Writing Modes Level 4. 30 July 2019. CR. URL: https://www.w3.org/TR/css-writing-modes-4/
[CSS2]
Bert Bos; et al. Cascading Style Sheets Level 2 Revision 1 (CSS 2.1) Specification. 7 June 2011. REC. URL: https://www.w3.org/TR/CSS21/
[CSSOM-1]
Daniel Glazman; Emilio Cobos Álvarez. CSS Object Model (CSSOM). 26 August 2021. WD. URL: https://www.w3.org/TR/cssom-1/
[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/
[HTML]
Anne van Kesteren; et al. HTML Standard. Living Standard. URL: https://html.spec.whatwg.org/multipage/
[RFC2119]
S. Bradner. Key words for use in RFCs to Indicate Requirement Levels. March 1997. Best Current Practice. URL: https://datatracker.ietf.org/doc/html/rfc2119
[WEB-ANIMATIONS-1]
Brian Birtles; et al. Web Animations. 8 September 2022. WD. URL: https://www.w3.org/TR/web-animations-1/
[WEBIDL]
Edgar Chen; Timothy Gu. Web IDL Standard. Living Standard. URL: https://webidl.spec.whatwg.org/

Informative References

[CSS-SCOPING-1]
Tab Atkins Jr.; Elika Etemad. CSS Scoping Module Level 1. 3 April 2014. WD. URL: https://www.w3.org/TR/css-scoping-1/
[SCROLL-ANIMATIONS-1]
Brian Birtles; et al. Scroll-linked Animations. 25 October 2022. WD. URL: https://www.w3.org/TR/scroll-animations-1/
[SELECTORS-4]
Elika Etemad; Tab Atkins Jr.. Selectors Level 4. 11 November 2022. WD. URL: https://www.w3.org/TR/selectors-4/

Property Index

Name Value Initial Applies to Inh. %ages Ani­mat­able Anim­ation type Canonical order Com­puted value
animation-delay [ <'animation-delay-start'> <'animation-delay-end'>? | <timeline-range-name> ]# see individual properties see individual properties see individual properties see individual properties see individual properties per grammar see individual properties
animation-delay-end [ <time> | <timeline-range-name> <percentage> ] 0s all elements no relative to the specified named timeline range no per grammar list, each item either a duration or a timeline range and progress percentage
animation-delay-start [ <time> | <timeline-range-name> <percentage> ]# 0s all elements no relative to the specified named timeline range no per grammar list, each item either a duration or a timeline range and progress percentage
animation-range [ <'animation-delay-start'> <'animation-delay-end'>? | <timeline-range-name> ]# see individual properties see individual properties see individual properties see individual properties see individual properties per grammar see individual properties
scroll-timeline <'scroll-timeline-name'> || <'scroll-timeline-axis'> see individual properties scroll containers no see individual properties not animatable per grammar see individual properties
scroll-timeline-axis block | inline | vertical | horizontal block scroll containers no n/a not animatable per grammar the specified keyword
scroll-timeline-name none | <custom-ident> none scroll containers no n/a not animatable per grammar the specified keyword
view-timeline [ <'view-timeline-name'> || <'view-timeline-axis'> ]# see individual properties all elements see individual properties see individual properties see individual properties per grammar see individual properties
view-timeline-axis [ block | inline | vertical | horizontal ]# block all elements no n/a not animatable per grammar a list of the keywords specified
view-timeline-inset [ [ auto | <length-percentage> ]{1,2} ]# 0 all elements no relative to the corresponding dimension of the relevant scrollport by computed value type per grammar a list consisting of two-value pairs representing the start and end insets each as either the keyword auto or a computed <length-percentage> value
view-timeline-name none | <custom-ident># none all elements no n/a not animatable per grammar the keyword none or a list of <custom-ident>s

IDL Index

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

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

[Exposed=Window]
interface AnimationTimeline {
  readonly attribute CSSNumberish? currentTime;
  CSSNumericValue? getCurrentTime(optional CSSOMString rangeName);
};

Issues Index

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%.
Should this be entry or enter?
Insert diagrams.
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?
Figure out how to incorporate fit/inset abilities.
Should it reset view-timeline-inset also?
Do we want to expand this scope to preceding siblings and/or distant cousins?
This section should move to CSS-ANIMATIONS-2 and WEB-ANIMATIONS-2.