- - The left figure shows the initial position of the balls.
- The right figure shows them after they have collided. -
-
- @media (prefers-reduced-motion: no-preference) {
- div.circle {
- 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;
- scroll-offsets: 200px, 300px;
- }
-
- @scroll-timeline union-timeline {
- source: selector(#container);
- orientation: block;
- scroll-offsets: 250px, 300px;
- }
-
- @keyframes left-circle {
- to { transform: translate(300px) }
- }
- @keyframes right-circle {
- to { transform: translate(350px) }
- }
- @keyframes union-circle {
- to { opacity: 1 }
- }
- }
-
-
-Using the programming interface, we might write this as:
-
-
- if (window.matchMedia('(prefers-reduced-motion: no-preference)').matches) {
- const scrollableElement = document.querySelector('#container');
-
- const collisionTimeline = new ScrollTimeline({
- source: scrollableElement,
- scrollOffsets: [CSS.px(200), CSS.px(300)]
- });
-
- const left = leftCircle.animate({ transform: 'translate(300px)' });
- left.timeline = collisionTimeline;
-
- const right = leftCircle.animate({ transform: 'translate(350px)' });
- right.timeline = collisionTimeline;
-
- const union = unionCircle.animate({ opacity: 1 }, { fill: "forwards" });
- union.timeline = new ScrollTimeline({
- source: scrollableElement,
- scrollOffsets: [CSS.px(250), CSS.px(300)]
- });
- }
-
-
-## 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.
-
-
-
- @media (prefers-reduced-motion: no-preference) {
- @scroll-timeline progress-timeline {
- source: selector(#body);
- scroll-offsets: 0, 100%;
- }
-
- @keyframes progress {
- to { width: 100%; }
- }
- #progress {
- width: 0px;
- height: 30px;
- background: red;
- animation: 1s linear forwards progress progress-timeline;
- }
- }
-
-
-
-If we use this API for this case, the example code will be as follow:
-
-
- if (window.matchMedia('(prefers-reduced-motion: no-preference)').matches) {
- var animation = div.animate({ width: '100%' }, { fill: "forwards" });
- animation.timeline = new ScrollTimeline(
- {
- scrollOffsets: [0, CSS.percent(100)]
- }
- );
- }
-
-
-## 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
-
-
-
-
-
-# Scroll-driven animations # {#scroll-driven-animations}
-
-## Scroll timelines ## {#scroll-timelines}
-
-### The {{ScrollDirection}} enumeration ### {#scrolldirection-enumeration}
-
-
-enum ScrollDirection {
- "block",
- "inline",
- "horizontal",
- "vertical"
-};
-
-
-The {{ScrollDirection}} enumeration specifies a direction of scroll of a
-scrollable element.
-
-
-enum ScrollTimelineAutoKeyword { "auto" };
-
-typedef (CSSNumericValue or CSSKeywordish) ContainerBasedOffset;
-typedef (ContainerBasedOffset or ElementBasedOffset) ScrollTimelineOffset;
-
-dictionary ScrollTimelineOptions {
- Element? source;
- ScrollDirection orientation = "block";
- sequence<ScrollTimelineOffset> scrollOffsets = [];
-};
-
-[Exposed=Window]
-interface ScrollTimeline : AnimationTimeline {
- constructor(optional ScrollTimelineOptions options = {});
- readonly attribute Element? source;
- readonly attribute ScrollDirection orientation;
- readonly attribute FrozenArray<ScrollTimelineOffset> scrollOffsets;
-};
-
-
-A scroll timeline is an {{AnimationTimeline}} whose time values are
-determined not by wall-clock time, but by the progress of scrolling in a
-[=scroll container=].
-
-The {{EffectTiming/duration}} of a scroll timeline is 100%.
-
-
-enum Edge { "start", "end" };
-
-dictionary ElementBasedOffset {
- Element target;
- Edge edge = "start";
- double threshold = 0.0;
-};
-
-
-
-
- |threshold amount| = {{ElementBasedOffset/threshold}} × |target dimension|
-
-
-
- 1. Adjust |scroll offset| by |threshold amount| as follow:
- 
- 
-
- 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,
- scrollOffsets: [{target: image, edge: 'end'},
- {target: image, edge: 'start'}],
- });
-
- const slideIn = target.animate({
- transform: ['translateX(0)', 'translateX(50vw)'],
- opacity: [0, 1]
- }, {
- timeline:timeline
- }
- );
- }
+ 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.
+
+# Scroll Progress Timelines # {#scroll-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 [=timeline inactive state/inactive=].
+
+ [=Scroll progress timelines=] can be referenced in 'animation-timeline'
+ anonymously using the ''scroll()'' [=functional notation=]
+ or by name (see [[#timeline-scope]])
+ after declaring them using the 'scroll-timeline' properties.
+ In the Web Animations API,
+ they can be represented anonymously by a {{ScrollTimeline}} object.
+
+## Anonymous Scroll Progress Timelines ## {#scroll-timelines-anonymous}
+
+### The ''scroll()'' notation ### {#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( <>? <>? )
+ <> = block | inline | vertical | horizontal
+ <> = root | nearest | <>
- The same logic can be done in CSS markup:
-
-
- @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);
- scroll-offsets: selector(#image) end, selector(#image) start;
- }
-
- #target {
- animation-name: slide-in;
- animation-timeline: image-in-scrollport;
- }
+ By default,
+ ''scroll()'' references the [=block axis=] of the nearest ancestor [=scroll container=].
+ Its arguments modify this lookup as follows:
+
+
+ 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;
+ };
- 1 / (size - 1).
- 1. Let interval progress be the result of evaluating
- (offset - start offset) /
- (end offset - start offset).
- 1. Return the result of evaluating
- (offset index + interval progress) ×
- offset weight.
-
- Note: This procedure guarantees that given offset belongs to
- scroll range within first and last offsets of scroll offsets.
- This is because the case when offset falls outside of the scroll
- range is handled before calling this procedure, as part of [=timeline/current time=]
- calculation.
-
- Note: The rationale behind choosing last matching offset in the array is to
- be consistent with {{findRule()}} method for finding which {{CSSKeyframeRule}}
- applies in a comma separated list of overlapping keyframes.
-|progress| × {{EffectTiming/duration}}
+ 1. Set the {{ScrollTimeline/axis}} property of |timeline|
+ to the corresponding value from |options|.
- <@scroll-timeline> = @scroll-timeline <- -An ''@scroll-timeline'' rule has a name given by the <> { < > } +## Named Scroll Progress Timelines ## {#scroll-timelines-named} -
+ Name: scroll-timeline-name + Value: none | <-Issue(5167): This will likely change in the future. + Specifies a name for the [=scroll progress timeline=] + associated with this [=scroll container=]. + The axis for this timeline is given by 'scroll-timeline-axis'. -### Scroll Timeline descriptors ### {#scroll-timeline-descriptors} +### Axis of a Scroll Progress Timeline: the 'scroll-timeline-axis' property ### {#scroll-timeline-axis} +> + Initial: none + Applies to: [=scroll containers=] + Inherited: no + Computed value: the specified keyword + Animation type: not animatable +
+ Name: scroll-timeline-axis + Value: block | inline | vertical | horizontal + Initial: block + Applies to: [=scroll containers=] + Inherited: no + Computed value: the specified keyword + Animation type: not animatable +-
- Name: source - For: @scroll-timeline - Value: selector( <+ Specifies an axis for the [=scroll progress timeline=] + associated with this [=scroll container=]. + The name for this timeline is given by 'scroll-timeline-name'. -'source' descriptor determines the scroll timeline's {{ScrollTimeline/source}}, -with the following values: + Values are as defined for ''scroll()''. -> ) | auto | none - Initial: auto -
+ Name: scroll-timeline + Value: <<'scroll-timeline-axis'>> || <<'scroll-timeline-name'>> + Applies to: [=scroll containers=] + Inherited: no + Animation type: not animatable +- : none - :: null. + This property is a [=shorthand=] for setting + 'scroll-timeline-name' and 'scroll-timeline-axis' + in a single declaration. + +# View Progress Timelines # {#view-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 [[#timeline-scope]]) + 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. + +## Anonymous View Progress Timelines ## {#view-timelines-anonymous} + +### The {{ViewTimeline}} Interface ### {#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;
+ };
+
- Issue: What does "null." mean?
-- Name: orientation - For: @scroll-timeline - Value: auto | block | inline | horizontal | vertical - Initial: auto -+ ISSUE: 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? -'orientation' descriptor determines the scroll timeline's {{ScrollTimeline/orientation}}. + Inherited attributes: -Issue: Define these values. +
- Name: scroll-offsets - For: @scroll-timeline - Value: none | <+ : {{ScrollTimeline/axis}} (inherited from {{ScrollTimeline}}) + :: Specifies the axis of scrolling + that drives the progress of the timeline. + See <># - Initial: none -
- <scroll-timeline-offset> = auto | <+ 1. Let |timeline| be the new {{ViewTimeline}} object. -The offset type depends on the value of <> | < > - <element-offset> = selector( < > ) [< > || < >]? - <element-offset-edge> = start | end -
-[Exposed=Window]
-interface CSSScrollTimelineRule : CSSRule {
- readonly attribute CSSOMString name;
- readonly attribute CSSOMString source;
- readonly attribute CSSOMString orientation;
- readonly attribute CSSOMString scrollOffsets;
-};
-
+ 1. Set the {{ViewTimeline/subject}} and {{ScrollTimeline/axis}} properties of |timeline|
+ to the corresponding values from |options|.
-"@scroll-timeline" followed by a SPACE (U+0020).
- 1. The result of performing serialize an identifier on the rule's
- {{CSSScrollTimelineRule/name}}, followed by a SPACE (U+0020).
- 1. A single LEFT CURLY BRACKET (U+007B), followed by a SPACE (U+0020).
- 1. If the 'source' descriptor is missing, the empty string.
- Otherwise, the concatenation of the following:
- 1. The string "source:", followed by a SPACE (U+0020).
- 1. One of the following,
- depending on the value of the 'source' descriptor:
- "orientation:",
- followed by a SPACE (U+0020).
- 1. The result of performing serialize an identifier
- on the value of the 'orientation' descriptor,
- followed by a SEMICOLON (U+003B),
- followed by a SPACE (U+0020).
- 1. If the 'scroll-offsets' descriptor is missing, the empty string.
- Otherwise, the concatenation of the following:
- 1. The string "scrollOffsets:",
- followed by a SPACE (U+0020),
- followed by a LEFT SQUARE BRACKET (U+005B).
- 1. For each value in the list for the rule's 'scroll-offsets'
- descriptor:
- 1. The result of performing
- serialize a scroll timeline offset on the value.
- 1. If not the last value,
- A COMMA (U+002C), followed by a SPACE (U+0020).
- 1. A RIGHT SQUARE BRACKET (U+005D),
- followed by a SEMICOLON (U+003B),
- followed by a SPACE (U+0020).
- 1. A single RIGHT CURLY BRACKET (U+007D).
-"selector",
- followed by LEFT PARENTHESIS (U+0028).
- 2. The result of performing serialize a selector
- on the selector() function's argument.
- 3. A single RIGHT PARENTHESIS (U+0029).
-
- #progress {
- position: fixed;
- top: 0;
- width: 0;
- height: 2px;
- background-color: red;
- }
-
-
- if (window.matchMedia('(prefers-reduced-motion: no-preference)').matches) {
- let progress = document.getElementById("progress");
- let effect = new KeyframeEffect(
- progress,
- [
- { width: "0vw" },
- { width: "100vw" }
- ],
- {
- easing: "linear",
- fill: "forwards"
- });
- let timeline = new ScrollTimeline({
- source: document.documentElement,
- orientation: "vertical",
- });
- let animation = new Animation(effect, timeline);
- animation.play();
- }
-
-
- @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-fill-mode: forwards;
- animation-timing-function: linear;
- }
-
- }
+
+ Name: view-timeline-name
+ Value: none | <>#
+ Initial: none
+ Applies to: all elements
+ Inherited: no
+ Computed value: the keyword ''view-timeline-name/none'' or a list of <>s
+ Animation type: not animatable
-No. +
+ Name: view-timeline-axis + Value: [ block | inline | vertical | horizontal ]# + Initial: block + Applies to: all elements + Inherited: no + Computed value: a list of the keywords specified + Animation type: not animatable +-
No. + 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. + +### Inset of a View Progress Timeline: the 'view-timeline-inset' property ### {#view-timeline-inset} + +
+ Name: view-timeline-inset + Value: [ auto | <-> ]{1,4} + Initial: 0 + Applies to: all elements + Inherited: no + Percentages: relative to the corresponding dimension of the relevant scrollport + Computed value: per side, the keyword ''view-timeline-inset/auto'' or a computed < > value + Animation type: by computed value type +
No. + 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. -
No. +
No. +
No. + The 'view-timeline-inset' property assigns its values to each side + exactly as the 'margin' property does. -
No. + ISSUE: Should the initial value be zero or auto? -
No. + ISSUE: Do we need all the longhands? Seems like overkill... -
No. +### View Timeline Shorthand: the 'view-timeline' shorthand ### {#view-timeline-shorthand} -
No. +
+ Name: view-timeline + Value: [ <<'view-timeline-name'>> || <<'view-timeline-axis'>> ]# + Applies to: all elements +-
No. + 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'. -
No. + ISSUE: Should it reset 'view-timeline-inset' also? -
No. +# Named Timeline Scoping # {#timeline-scope} -
No differently. The website should not be able to determine that the user is - in an "incognito" mode using scroll-linked animations. + 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 -
No. + 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=]. -
Yes. + ISSUE: Do we want to expand this scope to preceding siblings and/or distant cousins? -
No. -
-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: Olga Gerchikov, Microsoft, gerchiko@microsoft.com -Editor: Elika J. Etemad / fantasai, Invited Expert, http://fantasai.inkedblade.net/contact, w3cid 35400 -Editor: Robert Flack, Google - -Former Editor: Majid Valipour, Google, majidvp@google.com, w3cid 81464 -Former editor: Mantaroh Yoshinaga -Former editor: Stephen McGruer, Google, smcgruer@google.com -Markup Shorthands: markdown yes --
-urlPrefix: https://html.spec.whatwg.org/multipage/browsers.html#concept-document-window; type: dfn; spec: html - text: document associated with a window; url: concept-document-window --
-spec:html; - type:dfn; for:/; text:browsing context - type:method; text:requestAnimationFrame() -spec: cssom-view-1; type: dfn; - text: overflow direction; - text: css layout box -- - - -# Introduction # {#intro} - - 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=] - -## 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 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. - -## 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 - 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. - -# Scroll Progress Timelines # {#scroll-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 [=timeline inactive state/inactive=]. - - [=Scroll progress timelines=] can be referenced in 'animation-timeline' - anonymously using the ''scroll()'' [=functional notation=] - or by name (see [[#timeline-scope]]) - after declaring them using the 'scroll-timeline' properties. - In the Web Animations API, - they can be represented anonymously by a {{ScrollTimeline}} object. - -## Anonymous Scroll Progress Timelines ## {#scroll-timelines-anonymous} - -### The ''scroll()'' notation ### {#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( <- - By default, - ''scroll()'' references the [=block axis=] of the nearest ancestor [=scroll container=]. - Its arguments modify this lookup as follows: - ->? < >? ) - < > = block | inline | vertical | horizontal - <> = root | nearest | <> -
- 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 {{Animatable/animate()}} method
- to link the animation to a [=scroll progress timeline=].
-
- - Name: scroll-timeline-name - Value: none | <- - Specifies a name for the [=scroll progress timeline=] - associated with this [=scroll container=]. - The axis for this timeline is given by 'scroll-timeline-axis'. - -### Axis of a Scroll Progress Timeline: the 'scroll-timeline-axis' property ### {#scroll-timeline-axis} - -> - Initial: none - Applies to: [=scroll containers=] - Inherited: no - Computed value: the specified keyword - Animation type: not animatable -
- Name: scroll-timeline-axis - Value: block | inline | vertical | horizontal - Initial: block - Applies to: [=scroll containers=] - Inherited: no - Computed value: the specified keyword - 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()''. - -### Scroll Timeline Shorthand: the 'scroll-timeline' shorthand ### {#scroll-timeline-shorthand} - -
- Name: scroll-timeline - Value: <<'scroll-timeline-axis'>> || <<'scroll-timeline-name'>> - Applies to: [=scroll containers=] - Inherited: no - Animation type: not animatable -- - This property is a [=shorthand=] for setting - 'scroll-timeline-name' and 'scroll-timeline-axis' - in a single declaration. - -# View Progress Timelines # {#view-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 [[#timeline-scope]]) - 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. - -## Anonymous View Progress Timelines ## {#view-timelines-anonymous} - -### The {{ViewTimeline}} Interface ### {#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 {{Animatable/animate()}} method
- to link the animation to a [=view progress timeline=].
-
- - Name: view-timeline-name - Value: none | <- - 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. - -### Axis of a View Progress Timeline: the 'view-timeline-axis' property ### {#view-timeline-axis} - -># - Initial: none - Applies to: all elements - Inherited: no - Computed value: the keyword ''view-timeline-name/none'' or a list of < >s - Animation type: not animatable -
- Name: view-timeline-axis - Value: [ block | inline | vertical | horizontal ]# - Initial: block - Applies to: all elements - Inherited: no - Computed value: a list of the keywords specified - 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. - -### Inset of a View Progress Timeline: the 'view-timeline-inset' property ### {#view-timeline-inset} - -
- Name: view-timeline-inset - Value: [ auto | <- - 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. - -> ]{1,4} - Initial: 0 - Applies to: all elements - Inherited: no - Percentages: relative to the corresponding dimension of the relevant scrollport - Computed value: per side, the keyword ''view-timeline-inset/auto'' or a computed < > value - Animation type: by computed value type -
- Name: view-timeline - Value: [ <<'view-timeline-name'>> || <<'view-timeline-axis'>> ]# - Applies to: all elements -- - 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'. - - ISSUE: Should it reset 'view-timeline-inset' also? - -# Named Timeline Scoping # {#timeline-scope} - - 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=]. - - ISSUE: Do we want to expand this scope to preceding siblings and/or distant cousins? - -# Avoiding cycles with layout # {#avoiding-cycles} - - 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.