-
Notifications
You must be signed in to change notification settings - Fork 22.4k
/
index.md
473 lines (351 loc) · 17.5 KB
/
index.md
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
---
title: animation-timeline
slug: Web/CSS/animation-timeline
page-type: css-property
status:
- experimental
browser-compat: css.properties.animation-timeline
---
{{CSSRef}}{{SeeCompatTable}}
The **`animation-timeline`** [CSS](/en-US/docs/Web/CSS) property specifies the timeline that is used to control the progress of a CSS animation.
The following types of timelines can be set via `animation-timeline`:
- The default document timeline, which is progressed through by the passing of time since the document was first loaded in the browser. This is the timeline traditionally associated with CSS animations and is selected with a value of `auto`, or by not specifying an `animation-timeline` value at all.
- A _scroll progress timeline_, which is progressed through by scrolling a scrollable element (_scroller_) between top and bottom (or left and right). The position in the scroll range is converted into a percentage of progress — 0% at the start and 100% at the end. The element that provides the scroll progress timeline can be specified in two ways:
- A _named scroll progress timeline_ is one where the scroller providing the scroll progress timeline is explicitly named using the {{cssxref("scroll-timeline-name")}} property (or the {{cssxref("scroll-timeline")}} shorthand property). The name is then linked to the element to animate by specifying it as the value of that element's `animation-timeline` property.
- An _anonymous scroll progress timeline_ is one where the element to animate is given a {{cssxref("animation-timeline/scroll", "scroll()")}} function as an `animation-timeline` value, which selects the scroller providing the scroll progress timeline and the scroll axis to be used based on the arguments you pass to it.
- A _view progress timeline_, which is progressed through based on the change in visibility of an element (known as the _subject_) inside a scroller. The visibility of the subject inside the scroller is tracked — by default, the timeline is at 0% when the subject is first visible at one edge of the scroller, and 100% when it reaches the opposite edge. Unlike with scroll progress timelines, you can't specify the scroller — the subject's visibility is always tracked within its nearest ancestor scroller. The subject that provides the view progress timeline can be specified in two ways:
- A _named view progress timeline_ is one where the subject is explicitly named using the {{cssxref("view-timeline-name")}} property (or the {{cssxref("view-timeline")}} shorthand property). The name is then linked to the element to animate by specifying it as the value of that element's `animation-timeline` property. This is a key point — with named view progress timelines, the element to animate does not have to be the same as the subject.
- An _anonymous view progress timeline_ is one where the subject is given a {{cssxref("animation-timeline/view", "view()")}} function as an `animation-timeline` value, causing it to be animated based on its position inside its nearest parent scroller.
> **Note:** {{cssxref("animation-timeline")}} is included in the {{cssxref("animation")}} shorthand as a reset-only value. This means that including `animation` resets a previously-declared `animation-timeline` value to `auto`, but a specific value cannot be set via `animation`. When creating [CSS scroll-driven animations](/en-US/docs/Web/CSS/CSS_scroll-driven_animations), you need to declare `animation-timeline` after declaring any `animation` shorthand for it to take effect.
<!-- {{EmbedInteractiveExample("pages/css/animation-name.html")}} -->
## Syntax
```css
/* Keyword */
animation-timeline: none;
animation-timeline: auto;
/* Single animation named timeline */
animation-timeline: --timeline_name;
/* Single animation anonymous scroll progress timeline */
animation-timeline: scroll();
animation-timeline: scroll(scroller axis);
/* Single animation anonymous view progress timeline */
animation-timeline: view();
animation-timeline: view(axis inset);
/* Multiple animations */
animation-timeline: --progressBarTimeline, --carouselTimeline;
animation-timeline: none, --slidingTimeline;
/* Global values */
animation-timeline: inherit;
animation-timeline: initial;
animation-timeline: revert;
animation-timeline: revert-layer;
animation-timeline: unset;
```
### Values
- `none`
- : The animation is not associated with a timeline.
- `auto`
- : The animation's timeline is the document's default [DocumentTimeline](/en-US/docs/Web/API/DocumentTimeline).
- `scroll()`
- : An anonymous scroll progress timeline is provided by some ancestor scroller of the current element. The function parameters allow you to select the scroller, and the scrolling axis the timeline will be measured along.
See {{cssxref("animation-timeline/scroll", "scroll()")}} for more information.
- `view()`
- : An anonymous view progress timeline is provided by the subject that `animation-timeline: view();` is set on. The function parameters allow you to select the scrollbar axis along which timeline progress will be tracked and an inset that adjusts the position of the box in which the subject is deemed to be visible.
See {{cssxref("animation-timeline/view", "view()")}} for more information.
- `<dashed-ident>`
- : A {{cssxref('dashed-ident')}} identifying a named timeline previously declared with the {{cssxref('scroll-timeline-name')}} or {{cssxref('view-timeline-name')}} property (or the {{cssxref('scroll-timeline')}} or {{cssxref('view-timeline')}} shorthand property).
> **Note:** If two or more timelines share the same name, the last declared within the cascade will be used. Also, if no timeline is found that matches the given name, the animation is not associated with a timeline.
> **Note:** The [`<dashed-ident>`](/en-US/docs/Web/CSS/dashed-ident) values must start with `--`. This helps avoid name clashes with standard CSS keywords.
## Formal definition
{{cssinfo}}
## Formal syntax
{{csssyntax}}
## Examples
### Setting a named scroll progress timeline
A scroll progress timeline named `--squareTimeline` is defined using the `scroll-timeline-name` property on an element with an `id` of `container`.
This is then set as the timeline for the animation on the `#square` element using `animation-timeline: --squareTimeline`.
#### HTML
The HTML for the example is shown below.
```html
<div id="container">
<div id="square"></div>
<div id="stretcher"></div>
</div>
```
#### CSS
The CSS for the container sets it as the source of a scroll progress timeline named `--squareTimeline` using the `scroll-timeline-name` property (we could explicitly set which scrollbar axis to use with {{cssxref("scroll-timeline-axis")}}, but there is only a block direction scrollbar here, and it will be used by default).
The height of the container is set to 300px and we also set the container to create a vertical scrollbar if it overflows (below we will use CSS on the "stretcher" element to ensure that it does overflow).
```css
#container {
height: 300px;
overflow-y: scroll;
scroll-timeline-name: --squareTimeline;
position: relative;
}
```
The CSS below defines a square that rotates in alternate directions according to the timeline provided by the `animation-timeline` property, which is set to the `--squareTimeline` timeline named above.
```css
#square {
background-color: deeppink;
width: 100px;
height: 100px;
margin-top: 100px;
animation-name: rotateAnimation;
animation-duration: 1ms; /* Firefox requires this to apply the animation */
animation-direction: alternate;
animation-timeline: --squareTimeline;
position: absolute;
bottom: 0;
}
@keyframes rotateAnimation {
from {
transform: rotate(0deg);
}
to {
transform: rotate(360deg);
}
}
```
The "stretcher" CSS sets the block height to 600px, which forces the container element to overflow and create scroll bars.
Without this element there would be no scrollbar, and hence no scroll progress timeline to associate with the animation timeline.
```css
#stretcher {
height: 600px;
}
```
#### Result
Scroll to see the square element being animated.
{{EmbedLiveSample("Setting a named scroll progress timeline", "100%", "320px")}}
### Setting an anonymous scroll progress timeline
In this example, the `#square` element is animated using an anonymous scroll progress timeline, which is applied to the element to be animated using the `scroll()` function.
The timeline in this particular example is provided by the nearest parent element that has (any) scrollbar, from the scrollbar in the block direction.
#### HTML
The HTML for the example is shown below.
```html
<div id="container">
<div id="square"></div>
<div id="stretcher"></div>
</div>
```
#### CSS
The CSS below defines a square that rotates in alternate directions according to the timeline provided by the `animation-timeline` property.
In this case, the timeline is provided by `scroll(block nearest)`, which means that it will select the scrollbar in the block direction of the nearest ancestor element that has scrollbars; in this case the vertical scrollbar of the "container" element.
> **Note:** `block` and `nearest` are actually the default parameter values, so we could have used just `scroll()`.
```css
#square {
background-color: deeppink;
width: 100px;
height: 100px;
margin-top: 100px;
position: absolute;
bottom: 0;
animation-name: rotateAnimation;
animation-duration: 1ms; /* Firefox requires this to apply the animation */
animation-direction: alternate;
animation-timeline: scroll(block nearest);
}
@keyframes rotateAnimation {
from {
transform: rotate(0deg);
}
to {
transform: rotate(360deg);
}
}
```
The CSS for the container sets its height to 300px and we also set the container to create a vertical scrollbar if it overflows.
The "stretcher" CSS sets the block height to 600px, which forces the container element to overflow.
These two together ensure that the container has a vertical scrollbar, which allows it to be used as the source of the anonymous scroll progress timeline.
```css
#container {
height: 300px;
overflow-y: scroll;
position: relative;
}
#stretcher {
height: 600px;
}
```
#### Result
Scroll to see the square element being animated.
{{EmbedLiveSample("Setting an anonymous scroll progress timeline", "100%", "320px")}}
### Setting a named view progress timeline
A view progress timeline named `--subjectReveal` is defined using the `view-timeline-name` property on a subject element with a `class` of `animation`.
This is then set as the timeline for the same element using `animation-timeline: --subjectReveal;`. The result is that the subject element animates as it moves upwards through the document as it is scrolled.
#### HTML
The HTML for the example is shown below.
```html
<div class="content">
<h1>Content</h1>
<p>
Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod
tempor incididunt ut labore et dolore magna aliqua. Risus quis varius quam
quisque id. Et ligula ullamcorper malesuada proin libero nunc consequat
interdum varius. Elit ullamcorper dignissim cras tincidunt lobortis feugiat
vivamus at augue.
</p>
<p>
Dolor sed viverra ipsum nunc aliquet. Sed sed risus pretium quam vulputate
dignissim. Tortor aliquam nulla facilisi cras. A erat nam at lectus urna
duis convallis convallis. Nibh ipsum consequat nisl vel pretium lectus.
Sagittis aliquam malesuada bibendum arcu vitae elementum. Malesuada bibendum
arcu vitae elementum curabitur vitae nunc sed velit.
</p>
<div class="subject animation"></div>
<p>
Adipiscing enim eu turpis egestas pretium aenean pharetra magna ac. Arcu
cursus vitae congue mauris rhoncus aenean vel. Sit amet cursus sit amet
dictum. Augue neque gravida in fermentum et. Gravida rutrum quisque non
tellus orci ac auctor augue mauris. Risus quis varius quam quisque id diam
vel quam elementum. Nibh praesent tristique magna sit amet purus gravida
quis. Duis ultricies lacus sed turpis tincidunt id aliquet. In egestas erat
imperdiet sed euismod nisi. Eget egestas purus viverra accumsan in nisl nisi
scelerisque. Netus et malesuada fames ac.
</p>
</div>
```
#### CSS
The `subject` element and its containing `content` element are styled minimally, and the text content is given some basic font settings:
```css
.subject {
width: 300px;
height: 200px;
margin: 0 auto;
background-color: deeppink;
}
.content {
width: 75%;
max-width: 800px;
margin: 0 auto;
}
p,
h1 {
font-family: Arial, Helvetica, sans-serif;
}
h1 {
font-size: 3rem;
}
p {
font-size: 1.5rem;
line-height: 1.5;
}
```
The `<div>` with the class of `subject` is also given a class of `animation` — this is where the {{cssxref("view-timeline-name")}} is set to define a named view progress timeline. It is also given an `animation-timeline` name with the same value to declare that this will be the element animated as the view progress timeline is progressed.
Lastly, an animation is specified on the element that animates its opacity and scale, causing it to fade in and size up as it moves up the scroller.
```css
.animation {
view-timeline-name: --subjectReveal;
animation-timeline: --subjectReveal;
animation-name: appear;
animation-fill-mode: both;
animation-duration: 1ms; /* Firefox requires this to apply the animation */
}
@keyframes appear {
from {
opacity: 0;
transform: scaleX(0);
}
to {
opacity: 1;
transform: scaleX(1);
}
}
```
#### Result
Scroll to see the subject element being animated.
{{EmbedLiveSample("Setting a named view progress timeline", "100%", "480px")}}
### Setting an anonymous view progress timeline
An anonymous view progress timeline is set on an element with class `subject` using `animation-timeline: view()`. The result is that the `subject` element animates as it moves upwards through the document as it is scrolled.
#### HTML
The HTML for the example is shown below.
```html
<div class="content">
<h1>Content</h1>
<p>
Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod
tempor incididunt ut labore et dolore magna aliqua. Risus quis varius quam
quisque id. Et ligula ullamcorper malesuada proin libero nunc consequat
interdum varius. Elit ullamcorper dignissim cras tincidunt lobortis feugiat
vivamus at augue.
</p>
<p>
Dolor sed viverra ipsum nunc aliquet. Sed sed risus pretium quam vulputate
dignissim. Tortor aliquam nulla facilisi cras. A erat nam at lectus urna
duis convallis convallis. Nibh ipsum consequat nisl vel pretium lectus.
Sagittis aliquam malesuada bibendum arcu vitae elementum. Malesuada bibendum
arcu vitae elementum curabitur vitae nunc sed velit.
</p>
<div class="subject animation"></div>
<p>
Adipiscing enim eu turpis egestas pretium aenean pharetra magna ac. Arcu
cursus vitae congue mauris rhoncus aenean vel. Sit amet cursus sit amet
dictum. Augue neque gravida in fermentum et. Gravida rutrum quisque non
tellus orci ac auctor augue mauris. Risus quis varius quam quisque id diam
vel quam elementum. Nibh praesent tristique magna sit amet purus gravida
quis. Duis ultricies lacus sed turpis tincidunt id aliquet. In egestas erat
imperdiet sed euismod nisi. Eget egestas purus viverra accumsan in nisl nisi
scelerisque. Netus et malesuada fames ac.
</p>
</div>
```
#### CSS
The `subject` element and its containing `content` element are styled minimally, and the text content is given some basic font settings:
```css
.subject {
width: 300px;
height: 200px;
margin: 0 auto;
background-color: deeppink;
}
.content {
width: 75%;
max-width: 800px;
margin: 0 auto;
}
p,
h1 {
font-family: Arial, Helvetica, sans-serif;
}
h1 {
font-size: 3rem;
}
p {
font-size: 1.5rem;
line-height: 1.5;
}
```
The `<div>` with the class of `subject` is also given a class of `animation` — this is where `animation-timeline: view()` is set to declare that it will be animated as it progresses through the view progress timeline provided by its scrolling ancestor (in this case the document's root element).
Last, an animation is specified on the element that animates its opacity and scale, causing it to fade in and size up as it moves up the scroller.
```css
.animation {
animation-timeline: view();
animation-name: appear;
animation-fill-mode: both;
animation-duration: 1ms; /* Firefox requires this to apply the animation */
}
@keyframes appear {
from {
opacity: 0;
transform: scaleX(0);
}
to {
opacity: 1;
transform: scaleX(1);
}
}
```
#### Result
Scroll to see the subject element being animated.
{{EmbedLiveSample("Setting an anonymous view progress timeline", "100%", "480px")}}
## Specifications
{{Specifications}}
## Browser compatibility
{{Compat}}
## See also
- {{cssxref("animation")}}, {{cssxref("animation-composition")}}, {{cssxref("animation-delay")}}, {{cssxref("animation-direction")}}, {{cssxref("animation-duration")}}, {{cssxref("animation-fill-mode")}}, {{cssxref("animation-iteration-count")}}, {{cssxref("animation-name")}}, {{cssxref("animation-play-state")}}, {{cssxref("animation-timing-function")}}
- {{cssxref("scroll-timeline-name")}}, {{cssxref("scroll-timeline-axis")}}, {{cssxref("scroll-timeline")}}
- {{cssxref("timeline-scope")}}
- {{cssxref("view-timeline-name")}}, {{cssxref("view-timeline-axis")}}, {{cssxref("view-timeline")}}, {{cssxref("view-timeline-inset")}}
- The JavaScript equivalent: The `timeline` property available in {{domxref("Element.animate()")}} calls
- [CSS scroll-driven animations](/en-US/docs/Web/CSS/CSS_scroll-driven_animations)
- [Using CSS animations](/en-US/docs/Web/CSS/CSS_animations/Using_CSS_animations)