css3-animations/Overview.src.html@5df9b029337c
css3-animations/Overview.src.html
Mon, 04 Feb 2013 21:51:58 -0700
- author
- L. David Baron <dbaron@dbaron.org>
- date
- Mon, 04 Feb 2013 21:51:58 -0700
- changeset 7313
- 5df9b029337c
- parent 7230
- 550175952d0f
- child 7391
- f4da51999dd9
- permissions
- -rw-r--r--
[css3-animations][css3-transitions] Add warning about dynamic content causing seizures, with link to WCAG.
Fixes:
https://www.w3.org/Bugs/Public/show_bug.cgi?id=14669
https://www.w3.org/Style/CSS/Tracker/actions/399
as resolved in:
http://lists.w3.org/Archives/Public/www-style/2011Nov/0712.html
1 <!DOCTYPE html>
2 <html lang="en">
3 <head>
4 <title>CSS Animations</title>
5 <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
6 <link rel="stylesheet" type="text/css" href="../default.css">
7 <link rel="stylesheet" type="text/css" href="http://www.w3.org/StyleSheets/TR/W3C-ED.css">
8 <style type="text/css">
9 div.prod { margin: 1em 2em; }
10 </style>
11 </head>
13 <body>
15 <div class="head">
16 <!--logo-->
18 <h1>CSS Animations</h1>
20 <h2 class="no-num no-toc">[LONGSTATUS] [DATE]</h2>
21 <dl>
22 <dt>This version:
23 <dd><a href="[VERSION]">http://dev.w3.org/csswg/css3-animations/</a>
24 <!--http://www.w3.org/TR/[YEAR]/WD-[SHORTNAME]-[CDATE]/-->
25 <dt>Latest version:
26 <dd><a
27 href="http://www.w3.org/TR/css3-animations/">[LATEST]</a>
28 <dt>Editor's draft:
29 <dd><a href="http://dev.w3.org/csswg/[SHORTNAME]/">http://dev.w3.org/csswg/[SHORTNAME]/</a>
31 <dt>Previous version:
32 <dd><a href="http://www.w3.org/TR/2012/WD-css3-animations-20120403/">
33 http://www.w3.org/TR/2012/WD-css3-animations-20120403/</a>
34 <dt id="editors-list">Editors:
35 <dd><a href="mailto:dino@apple.com">Dean Jackson</a> (<a
36 href="http://www.apple.com/">Apple Inc</a>)
37 <dd><a href="mailto:hyatt@apple.com">David Hyatt</a> (<a
38 href="http://www.apple.com/">Apple Inc</a>)
39 <dd><a href="mailto:cmarrin@apple.com">Chris Marrin</a> (<a
40 href="http://www.apple.com/">Apple Inc</a>)
41 <dd><a href="mailto:sylvaing@microsoft.com">Sylvain Galineau</a>
42 (<a class=org href="http://www.microsoft.com/">Microsoft</a>)
43 <dd class=vcard><a class=fn href="http://dbaron.org/">L. David Baron</a>
44 (<a class=org href="http://www.mozilla.org/">Mozilla</a>)
46 <dt>Issues list:
47 <dd><a href="https://www.w3.org/Bugs/Public/buglist.cgi?query_format=advanced&product=CSS&component=Animations&resolution=---&cmdtype=doit">in Bugzilla</a>
49 <dt>Discussion:
50 <dd><a href="http://lists.w3.org/Archives/Public/www-style/">www-style@w3.org</a> with subject line “<kbd>[[SHORTNAME]] <var>… message topic …</var></kbd>”
52 <dt>Test suite:
53 <dd>none yet
54 </dl>
56 <!--copyright-->
58 <hr title="Separator for header">
59 </div>
61 <h2 class="no-num no-toc" id="abstract">
62 Abstract</h2>
64 <p>
65 This CSS module describes a way for authors to animate the values of CSS properties over time,
66 using keyframes.
67 The behavior of these keyframe animations can be controlled by specifying their duration,
68 number of repeats,
69 and repeating behavior.
72 <h2 class="no-num no-toc" id="status">
73 Status of this document</h2>
74 <!--status-->
77 <h2 class="no-num no-toc" id="contents">
78 Table of contents</h2>
79 <!--toc-->
82 <h2 id="introduction">
83 Introduction</h2>
85 <p><em>This section is not normative.</em>
87 <p>
88 CSS Transitions [[CSS3-TRANSITIONS]]
89 provide a way to interpolate CSS property values
90 when they change as a result of underlying property changes.
91 This provides an easy way to do simple animation,
92 but the start and end states of the animation are controlled by the existing property values,
93 and transitions provide little control to the author on how the animation progresses.
95 <p>
96 This proposal introduces <dfn>defined animations</dfn>,
97 in which the author can specify the changes in CSS properties over time as a set of keyframes.
98 Animations are similar to transitions
99 in that they change the presentational value of CSS properties over time.
100 The principal difference is that
101 while transitions trigger <em>implicitly</em> when property values change,
102 animations are <em>explicitly</em> executed when the animation properties are applied.
103 Because of this,
104 animations require explicit values for the properties being animated.
105 These values are specified using animation keyframes, described below.
107 <p>
108 Many aspects of the animation can be controlled,
109 including how many times the animation iterates,
110 whether or not it alternates between the begin and end values,
111 and whether or not the animation should be running or paused.
112 An animation can also delay its start time.
115 <h2 id="animations">
116 Animations</h2>
118 <p>
119 CSS Animations affect computed property values.
120 During the execution of an animation,
121 the computed value for a property is controlled by the animation.
122 This overrides the value specified in the normal styling system.
123 Animations override all normal rules, but are overriden by
124 !important rules.
126 <p>
127 If at one point in time there are multiple animations specifying behavior for the same property,
128 the animation whose name occurs last in the value of 'animation-name'
129 will override the other animations at that point.
132 <p>
133 An animation does not affect the computed value before the application of the animation,
134 before the animation delay has expired,
135 and after the end of the animation.
138 <div class="figure">
139 <img src="sandwich.png" alt="">
141 <p class="caption">
142 Computation of animated property values
143 </div>
145 <p>
146 The diagram above shows how property values are computed.
147 The intrinsic style is shown at the top of the diagram.
148 The computed value is derived from intrinsic style
149 at the times when an animation is not running
150 and also when an animation is delayed
151 (see below for specification of animation delay).
152 During an animation,
153 the computed style is derived from the animated value.
156 <p>
157 The start time of an animation is the latter of two moments:
158 the time at which the style is resolved that specifies the animation,
159 or the time the document's load event is fired.
160 Therefore, an animation specified in the document style sheet
161 will begin at the document load.
162 An animation specified on an element by modifying the style after the document has loaded
163 will start when the style is resolved.
164 That may be immediately in the case of a pseudo style rule such as hover,
165 or may be when the scripting engine returns control to the browser
166 (in the case of style applied by script).
169 <p>
170 An animation applies to an element
171 if the element has a value for 'animation-name' that references a valid keyframes rule.
172 Once an animation has started
173 it continues until it ends
174 or the 'animation-name' is removed.
175 The values used for the keyframes and animation properties are snapshotted at the time the animation starts.
176 Changing them during the execution of the animation has no effect.
177 Note also that changing the value of 'animation-name' does not necessarily restart an animation
178 (e.g., if a list of animations are applied and one is removed from the list,
179 only that animation will stop;
180 The other animations will continue).
181 In order to restart an animation,
182 it must be removed then reapplied.
185 <p>
186 The end of the animation is defined by the combination of the
187 'animation-duration',
188 'animation-iteration-count' and
189 'animation-fill-mode' properties.
192 <div class="example">
193 <pre>
194 div {
195 animation-name: diagonal-slide;
196 animation-duration: 5s;
197 animation-iteration-count: 10;
198 }
200 @keyframes diagonal-slide {
202 from {
203 left: 0;
204 top: 0;
205 }
207 to {
208 left: 100px;
209 top: 100px;
210 }
212 }</pre>
214 <p>
215 This will produce an animation
216 that moves an element from (0, 0) to (100px, 100px)
217 over five seconds
218 and repeats itself nine times
219 (for a total of ten iterations).
220 </div>
222 <p>
223 Setting the display property to 'none' will terminate any running animation
224 applied to the element and its descendants.
226 If an element has a display of 'none', updating display to a value other than 'none'
227 will start all animations applied to the element by the 'animation-name' property,
228 as well as all animations applied to descendants with display other than 'none'.
229 </p>
231 <p>
232 While authors can use animations to create dynamically changing content,
233 dynamically changing content can lead to seizures in some users.
234 For information on how to avoid content that can lead to seizures, see
235 <a href="http://www.w3.org/TR/WCAG20/#seizure">Guideline 2.3:
236 Seizures:
237 Do not design content in a way that is known to cause seizures</a>
238 ([[WCAG20]]).
239 </p>
241 <h2 id="keyframes">
242 Keyframes</h2>
243 <p>
244 Keyframes are used to specify the values for the animating properties
245 at various points during the animation.
246 The keyframes specify the behavior of one cycle of the animation;
247 the animation may iterate one or more times.
249 <p>
250 Keyframes are specified using a specialized CSS at-rule.
251 A @keyframes rule consists of the keyword "@keyframes",
252 followed by an identifier giving a name for the animation
253 (which will be referenced using 'animation-name'),
254 followed by a set of style rules
255 (delimited by curly braces).
257 <p>
258 The <dfn>keyframe selector</dfn> for a keyframe style rule
259 consists of a comma-separated list of percentage values
260 or the keywords 'from' or 'to'.
261 The selector is used to specify the percentage along the duration of the animation that the keyframe represents.
262 The keyframe itself is specified by the block of property values declared on the selector.
263 The keyword 'from' is equivalent to the value ''0%''.
264 The keyword 'to' is equivalent to the value ''100%''.
265 <span class='note'>Note that the percentage unit specifier must be used on percentage values.
266 Therefore, ''0'' is an invalid keyframe selector.</span>
268 <p>
269 If a ''0%'' or ''from'' keyframe is not specified,
270 then the user agent constructs a ''0%'' keyframe
271 using the computed values of the properties being animated.
272 If a ''100%'' or ''to'' keyframe is not specified,
273 then the user agent constructs a ''100%'' keyframe
274 using the computed values of the properties being animated.
275 If a keyframe selector specifies
276 negative percentage values or
277 values higher than 100%,
278 then the keyframe will be ignored.
280 <p>
281 The <dfn>keyframe declaration block</dfn> for a keyframe rule
282 consists of properties and values.
283 Properties that are unable to be animated are ignored in these rules,
284 with the exception of 'animation-timing-function',
285 the behavior of which is described below. In addition, keyframe rule declarations qualified with !important are ignored.
287 <p class="issue">
288 Need to describe what happens if a property is not present in all keyframes.
290 <p>
291 The @keyframes rule that is used by an animation
292 will be the last one encountered in sorted rules order
293 that matches the name of the animation specified by the 'animation-name' property.
294 @keyframes rules do not cascade;
295 therefore, an animation will never derive keyframes from more than one @keyframes rule.
297 <p class='note'>
298 Note that since empty @keyframes rule are valid, they may hide the keyframes of
299 those preceding animation definitions with a matching name.
301 <p>
302 To determine the set of keyframes,
303 all of the values in the selectors are sorted in increasing order by time.
304 If there are any duplicates,
305 then the last keyframe specified inside the @keyframes rule
306 will be used to provide the keyframe information for that time.
307 There is no cascading within a @keyframes rule if multiple keyframes specify the same keyframe selector values.
309 <p>
310 If a property is not specified for a keyframe,
311 or is specified but invalid,
312 the animation of that property proceeds as if that keyframe did not exist.
313 Conceptually,
314 it is as if a set of keyframes is constructed for each property that is present in any of the keyframes,
315 and an animation is run independently for each property.
317 <div class="example">
318 <pre>
319 @keyframes wobble {
320 0% {
321 left: 100px;
322 }
324 40% {
325 left: 150px;
326 }
328 60% {
329 left: 75px;
330 }
332 100% {
333 left: 100px;
334 }
335 }</pre>
337 <p>
338 Four keyframes are specified for the animation named "wobble".
339 In the first keyframe,
340 shown at the beginning of the animation cycle,
341 the value of the 'left' property being animated is ''100px''.
342 By 40% of the animation duration,
343 'left' has animated to ''150px''.
344 At 60% of the animation duration,
345 'left' has animated back to ''75px''.
346 At the end of the animation cycle,
347 the value of 'left' has returned to ''100px''.
348 The diagram below shows the state of the animation if it were given a duration of ''10s''.
350 <div class="figure">
351 <img src="animation1.png" alt="">
353 <p class="caption">
354 Animations states specified by keyframes
355 </div>
356 </div>
358 <p>
359 The following is the grammar for the keyframes rule.
361 <pre>
362 keyframes_rule: KEYFRAMES_SYM S+ IDENT S* '{' S* keyframes_blocks '}' S*;
364 keyframes_blocks: [ keyframe_selector '{' S* declaration? [ ';' S* declaration? ]* '}' S* ]* ;
366 keyframe_selector: [ FROM_SYM | TO_SYM | PERCENTAGE ] S* [ ',' S* [ FROM_SYM | TO_SYM | PERCENTAGE ] S* ]*;
368 @{K}{E}{Y}{F}{R}{A}{M}{E}{S} {return KEYFRAMES_SYM;}
369 {F}{R}{O}{M} {return FROM_SYM;}
370 {T}{O} {return TO_SYM;}</pre>
373 <h3 id="timing-functions">
374 Timing functions for keyframes</h3>
376 <p>
377 A keyframe style rule may also declare the timing function that is to be used
378 as the animation moves to the next keyframe.
380 <div class="example">
381 <pre>
382 @keyframes bounce {
384 from {
385 top: 100px;
386 animation-timing-function: ease-out;
387 }
389 25% {
390 top: 50px;
391 animation-timing-function: ease-in;
392 }
394 50% {
395 top: 100px;
396 animation-timing-function: ease-out;
397 }
399 75% {
400 top: 75px;
401 animation-timing-function: ease-in;
402 }
404 to {
405 top: 100px;
406 }
408 }</pre>
410 <p>
411 Five keyframes are specified for the animation named "bounce".
412 Between the first and second keyframe
413 (i.e., between 0% and 25%)
414 an ''ease-out'' timing function is used.
415 Between the second and third keyframe
416 (i.e., between 25% and 50%)
417 an ''ease-in'' timing function is used.
418 And so on.
419 The effect will appear as an element that moves up the page ''50px'',
420 slowing down as it reaches its highest point
421 then speeding up as it falls back to ''100px''.
422 The second half of the animation behaves in a similar manner,
423 but only moves the element ''25px'' up the page.
424 </div>
426 <p>
427 A timing function specified on the "to" or 100% keyframe is ignored.
429 <p>
430 See the 'animation-timing-function' property for more information.
433 <h3 id="animation-name-property">
434 The 'animation-name' Property</h3>
436 <p>
437 The 'animation-name' property defines a list of animations that apply.
438 Each name is used to select the keyframe at-rule
439 that provides the property values for the animation.
440 If the name does not match any keyframe at-rule,
441 there are no properties to be animated
442 and the animation will not execute.
443 Furthermore,
444 if the animation name is ''none''
445 then there will be no animation.
446 This can be used to override any animations coming from the cascade.
447 If multiple animations are attempting to modify the same property,
448 then the animation closest to the end of the list of names wins.
450 <p id="list-matching">
451 Each animation listed by name
452 should have a corresponding value for the other animation properties listed below.
453 If the lists of values for the other animation properties do not have the same length,
454 the length of the 'animation-name' list
455 determines the number of items in each list examined when starting animations.
456 The lists are matched up from the first value:
457 excess values at the end are not used.
458 If one of the other properties doesn't have enough comma-separated values to match the number of values of 'animation-name',
459 the UA must calculate its used value by repeating the list of values until there are enough.
460 This truncation or repetition does not affect the computed value.
461 <span class="note">Note: This is analogous to the behavior of the 'background-*'properties,
462 with 'background-image' analogous to 'animation-name'.</span>
465 <table class=propdef>
466 <tr>
467 <th>Name:</th>
468 <td><dfn>animation-name</dfn>
469 <tr>
470 <th><a href="#values">Value</a>:
471 <td><span><single-animation-name></span> [ ',' <span><single-animation-name></span> ]*
472 <tr>
473 <th>Initial:
474 <td>''none''
475 <tr>
476 <th>Applies To:
477 <td>all elements, ::before and ::after pseudo-elements
478 <tr>
479 <th>Inherited:
480 <td>no
481 <tr>
482 <th>Animatable:
483 <td>no
484 <tr>
485 <th>Percentages:
486 <td>N/A
487 <tr>
488 <th>Media:
489 <td>visual
490 <tr>
491 <th>Computed Value:
492 <td>As specified
493 <tr>
494 <th>Canonical Order:
495 <td><abbr title="follows order of property value definition">per grammar</abbr>
496 </table>
498 <div class="prod">
499 <dfn id="single-animation-name"><single-animation-name></dfn> = none | <IDENT>
500 </div>
502 <!--
503 <p>
504 It is possible for elements to have multiple animations running that change the same property or properties. In this case the animations combine in a manner defined by the property. For example, animations on 'opacity' will add together and animations on 'transform' will have their transformation matrices multiplied.
506 <div class="example">
507 <p style="display:none">
508 Example(s):
510 <pre>
511 @keyframes 'border-bloat' {
512 from {
513 border-width: 0;
514 }
515 to {
516 border-width: 10px;
517 }
518 }
520 @keyframes 'border-diet' {
521 from {
522 border-width: 4px;
523 }
524 to {
525 border-width: 2px;
526 }
527 }
529 div {
530 animation-name: 'border-bloat', 'border-diet';
531 animation-duration: 10s, 4s;
532 }
533 </pre>
534 <p>
535 The above example has two animations executing on the same property, 'border-width'. The animations are additive. That is, the
536 resulting value for the property will be the addition of the values from the
537 two animations.
539 <p>
540 At time '0s' the element's border will be 4px wide (0px from 'border-bloat' plus 4px from 'border-diet').
541 At time '4s' the element's border will be 6px wide (4px from 'border-bloat' plus 2px from 'border-diet').
542 At time '10s' the element's border will be 10px wide (10px from 'border-bloat' and no addition from
543 'border-diet' as it is no longer executing).
545 </div>
546 -->
549 <h3 id="animation-duration-property">
550 The 'animation-duration' Property</h3>
552 <p>
553 The 'animation-duration' property defines the length of time that an animation takes to complete one cycle.
556 <table class=propdef>
557 <tr>
558 <th>Name:</th>
559 <td><dfn>animation-duration</dfn>
560 <tr>
561 <th><a href="#values">Value</a>:
562 <td> <span><time></span> [, <span><time></span>]*
563 <tr>
564 <th>Initial:
565 <td>''0s''
566 <tr>
567 <th>Applies To:
568 <td>all elements, ::before and ::after pseudo-elements
569 <tr>
570 <th>Inherited:
571 <td>no
572 <tr>
573 <th>Animatable:
574 <td>no
575 <tr>
576 <th>Percentages:
577 <td>N/A
578 <tr>
579 <th>Media:
580 <td>visual
581 <tr>
582 <th>Computed Value:
583 <td>as specified
584 <tr>
585 <th>Canonical Order:
586 <td><abbr title="follows order of property value definition">per grammar</abbr>
587 </table>
589 <p>
590 The initial value is ''0s'',
591 meaning that the animation takes no time.
592 When the duration is ''0s'' 'animation-fill-mode' still applies,
593 so an animation that fills backwards
594 will show the value of the 0% keyframe during any delay period,
595 and an animation that fills forwards will retain the value specified at the 100% keyframe,
596 even if the animation was instantaneous.
597 Also, animation events are still fired.
598 A negative 'animation-duration' value renders the declaration invalid.
601 <h3 id="animation-timing-function-property">
602 The 'animation-timing-function' Property</h3>
604 <p>
605 The 'animation-timing-function' property describes how the animation will progress over one cycle of its duration.
606 See the 'transition-timing-function' property [[!CSS3-TRANSITIONS]] for a complete description of timing function calculation.
608 <table class=propdef>
609 <tr>
610 <th>Name:</th>
611 <td><dfn>animation-timing-function</dfn>
612 <tr>
613 <th><a href="#values">Value</a>:
614 <td><span><single-timing-function></span> [ ',' <span><single-timing-function></span> ]*
615 <tr>
616 <th>Initial:
617 <td>''ease''
618 <tr>
619 <th>Applies To:
620 <td>all elements, ::before and ::after pseudo-elements
621 <tr>
622 <th>Inherited:
623 <td>no
624 <tr>
625 <th>Animatable:
626 <td>no
627 <tr>
628 <th>Percentages:
629 <td>N/A
630 <tr>
631 <th>Media:
632 <td>visual
633 <tr>
634 <th>Computed Value:
635 <td>as specified
636 <tr>
637 <th>Canonical Order:
638 <td><abbr title="follows order of property value definition">per grammar</abbr>
639 </table>
641 <p>All the valid values of ''<single-timing-function>'' are defined by the 'transition-timing-function' property [[!CSS3-TRANSITIONS]].</p>
643 <p>
644 For a keyframed animation,
645 the 'animation-timing-function' applies between keyframes,
646 not over the entire animation.
647 For example,
648 in the case of an ''ease-in-out'' timing function,
649 an animation will ease in at the start of the keyframe
650 and ease out at the end of the keyframe.
651 An 'animation-timing-function' defined within a keyframe block applies to that keyframe,
652 otherwise the timing function specified for the animation is used.
655 <h3 id="animation-iteration-count-property">
656 The 'animation-iteration-count' Property</h3>
658 <p>
659 The 'animation-iteration-count' property specifies the number of times an animation cycle is played.
660 The initial value is ''1'',
661 meaning the animation will play from beginning to end once.
662 A value of ''infinite'' will cause the animation to repeat forever.
663 Non-integer numbers will cause the animation to end part-way through a cycle.
664 Negative values of 'animation-iteration-count' are invalid.
665 This property is often used in conjunction an 'animation-direction' value of ''alternate'',
666 which will cause the animation to play in reverse on alternate cycles.
668 <table class=propdef>
669 <tr>
670 <th>Name:</th>
671 <td><dfn>animation-iteration-count</dfn>
672 <tr>
673 <th><a href="#values">Value</a>:
674 <td><span><single-animation-iteration-count></span> [ ',' <span><single-animation-iteration-count></span> ]*
675 <tr>
676 <th>Initial:
677 <td>''1''
678 <tr>
679 <th>Applies To:
680 <td>all elements, ::before and ::after pseudo-elements
681 <tr>
682 <th>Inherited:
683 <td>no
684 <tr>
685 <th>Animatable:
686 <td>no
687 <tr>
688 <th>Percentages:
689 <td>N/A
690 <tr>
691 <th>Media:
692 <td>visual
693 <tr>
694 <th>Computed Value:
695 <td>as specified
696 <tr>
697 <th>Canonical Order:
698 <td><abbr title="follows order of property value definition">per grammar</abbr>
699 </table>
701 <div class="prod">
702 <dfn id="single-animation-iteration-count"><single-animation-iteration-count></dfn> =
703 infinite | <number>
704 </div>
706 <h3 id="animation-direction-property">
707 The 'animation-direction' Property</h3>
709 <p>
710 The 'animation-direction' property defines whether or not the animation should play in reverse on some or all cycles.
711 When an animation is played in reverse the timing functions are also reversed.
712 For example, when played in reverse an ease-in animation would appear to be an ease-out animation.
714 <table class=propdef>
715 <tr>
716 <th>Name:</th>
717 <td><dfn>animation-direction</dfn>
718 <tr>
719 <th><a href="#values">Value</a>:
720 <td><span><single-animation-direction></span> [ ',' <span><single-animation-direction></span> ]*
721 <tr>
722 <th>Initial:
723 <td>''normal''
724 <tr>
725 <th>Applies To:
726 <td>all elements, ::before and ::after pseudo-elements
727 <tr>
728 <th>Inherited:
729 <td>no
730 <tr>
731 <th>Animatable:
732 <td>no
733 <tr>
734 <th>Percentages:
735 <td>N/A
736 <tr>
737 <th>Media:
738 <td>visual
739 <tr>
740 <th>Computed Value:
741 <td>as specified
742 <tr>
743 <th>Canonical Order:
744 <td><abbr title="follows order of property value definition">per grammar</abbr>
745 </table>
747 <div class="prod">
748 <dfn id="single-animation-direction"><single-animation-direction></dfn> =
749 normal | reverse | alternate | alternate-reverse
750 </div>
752 <dl>
753 <dt><dfn>normal</dfn>
754 <dd>
755 All iterations of the animation are played as specified.
757 <dt><dfn>reverse</dfn>
758 <dd>
759 All iterations of the animation are played in the reverse direction from the way they were specified.
761 <dt><dfn>alternate</dfn>
762 <dd>
763 The animation cycle iterations that are odd counts are played in the normal direction,
764 and the animation cycle iterations that are even counts are played in a reverse direction.
766 <dt><dfn>alternate-reverse</dfn>
767 <dd>
768 The animation cycle iterations that are odd counts are played in the reverse direction,
769 and the animation cycle iterations that are even counts are played in a normal direction.
770 </dl>
772 <p class='note'>
773 Note that for the purpose of determining whether an iteration is even or odd,
774 iterations start counting from 1.
777 <h3 id="animation-play-state-property">
778 The 'animation-play-state' Property</h3>
780 <p>
781 The 'animation-play-state' property defines whether the animation is running or paused.
782 A running animation can be paused by setting this property to ''paused''.
783 To continue running a paused animation this property can be set to ''running''.
784 A paused animation will continue to display the current value of the animation in a static state,
785 as if the time of the animation is constant.
786 When a paused animation is resumed,
787 it restarts from the current value,
788 not necessarily from the beginning of the animation.
790 <table class=propdef>
791 <tr>
792 <th>Name:</th>
793 <td><dfn>animation-play-state</dfn>
794 <tr>
795 <th><a href="#values">Value</a>:
796 <td><span><single-animation-play-state></span> [ ',' <span><single-animation-play-state></span> ]*
797 <tr>
798 <th>Initial:
799 <td>''running''
800 <tr>
801 <th>Applies To:
802 <td>all elements, ::before and ::after pseudo-elements
803 <tr>
804 <th>Inherited:
805 <td>no
806 <tr>
807 <th>Animatable:
808 <td>no
809 <tr>
810 <th>Percentages:
811 <td>N/A
812 <tr>
813 <th>Media:
814 <td>visual
815 <tr>
816 <th>Computed Value:
817 <td>as specified
818 <tr>
819 <th>Canonical Order:
820 <td><abbr title="follows order of property value definition">per grammar</abbr>
821 </table>
823 <div class="prod">
824 <dfn id="single-animation-play-state"><single-animation-play-state></dfn> =
825 running | paused
826 </div>
828 <h3 id="animation-delay-property">
829 The 'animation-delay' Property</h3>
831 <p>
832 The 'animation-delay' property defines when the animation will start.
833 It allows an animation to begin execution some time after it is applied.
834 An 'animation-delay' value of ''0s'' means the animation will execute as soon as it is applied.
835 Otherwise, the value specifies an offset from the moment the animation is applied,
836 and the animation will delay execution by that offset.
838 <p>
839 If the value for 'animation-delay' is a negative time offset
840 then the animation will execute the moment it is applied,
841 but will appear to have begun execution at the specified offset.
842 That is, the animation will appear to begin part-way through its play cycle.
843 In the case where an animation has implied starting values and a negative 'animation-delay',
844 the starting values are taken from the moment the animation is applied.
846 <table class=propdef>
847 <tr>
848 <th>Name:</th>
849 <td><dfn>animation-delay</dfn>
850 <tr>
851 <th><a href="#values">Value</a>:
852 <td> <span><time></span> [, <span><time></span>]*
853 <tr>
854 <th>Initial:
855 <td>''0s''
856 <tr>
857 <th>Applies To:
858 <td>all elements, ::before and ::after pseudo-elements
859 <tr>
860 <th>Inherited:
861 <td>no
862 <tr>
863 <th>Animatable:
864 <td>no
865 <tr>
866 <th>Percentages:
867 <td>N/A
868 <tr>
869 <th>Media:
870 <td>visual
871 <tr>
872 <th>Computed Value:
873 <td>as specified
874 <tr>
875 <th>Canonical Order:
876 <td><abbr title="follows order of property value definition">per grammar</abbr>
877 </table>
880 <h3 id="animation-fill-mode-property">
881 The 'animation-fill-mode' Property</h3>
883 <p>
884 The 'animation-fill-mode' property defines what values are applied by the animation outside the time it is executing.
885 By default, an animation will not affect property values
886 between the time it is applied
887 (the 'animation-name' property is set on an element)
888 and the time it begins execution
889 (which is determined by the 'animation-delay' property).
890 Also, by default an animation does not affect property values after the animation ends
891 (determined by the 'animation-duration' property).
892 The 'animation-fill-mode' property can override this behavior.
894 <p>
895 If the value for 'animation-fill-mode' is ''backwards'',
896 then the animation will apply
897 the property values defined in the keyframe
898 that will start the first iteration of the animation,
899 during the period defined by 'animation-delay'.
900 These are either the values of the ''from'' keyframe
901 (when 'animation-direction' is ''normal'' or ''alternate'')
902 or those of the ''to'' keyframe
903 (when 'animation-direction' is ''reverse'' or ''alternate-reverse'').
905 <p>
906 If the value for 'animation-fill-mode' is ''forwards'',
907 then after the animation ends
908 (as determined by its 'animation-iteration-count'),
909 the animation will apply
910 the property values for the time the animation ended.
911 When 'animation-iteration-count' is an integer greater than zero,
912 the values applied will be
913 those for the end of the last completed iteration of the animation
914 (rather than the values for
915 the start of the iteration that would be next).
916 When 'animation-iteration-count' is zero,
917 the values applied will be those that would start the first iteration
918 (just as when 'animation-fill-mode' is ''backwards'').
920 <p>
921 If the value for 'animation-fill-mode' is ''both'',
922 then the animation will follow the rules for both 'forwards' and 'backwards'.
923 That is, it will extend the animation properties in both directions.
925 <table class=propdef>
926 <tr>
927 <th>Name:</th>
928 <td><dfn>animation-fill-mode</dfn>
929 <tr>
930 <th><a href="#values">Value</a>:
931 <td><span><single-animation-fill-mode></span> [ ',' <span><single-animation-fill-mode></span> ]*
932 <tr>
933 <th>Initial:
934 <td>''none''
935 <tr>
936 <th>Applies To:
937 <td>all elements, ::before and ::after pseudo-elements
938 <tr>
939 <th>Inherited:
940 <td>no
941 <tr>
942 <th>Animatable:
943 <td>no
944 <tr>
945 <th>Percentages:
946 <td>N/A
947 <tr>
948 <th>Media:
949 <td>visual
950 <tr>
951 <th>Computed Value:
952 <td>as specified
953 <tr>
954 <th>Canonical Order:
955 <td><abbr title="follows order of property value definition">per grammar</abbr>
956 </table>
958 <div class="prod">
959 <dfn id="single-animation-fill-mode"><single-animation-fill-mode></dfn> =
960 none | forwards | backwards | both
961 </div>
963 <h3 id="animation-shorthand-property">
964 The 'animation' Shorthand Property
966 <p>
967 The 'animation' shorthand property is a comma-separated list of
968 animation definitions, each of which combines seven of the animation properties
969 into a single component value.
971 <table class=propdef>
972 <tr>
973 <th>Name:</th>
974 <td><dfn>animation</dfn>
975 <tr>
976 <th><a href="#values">Value</a>:
977 <td><span><single-animation></span> [ ',' <span><single-animation></span> ]*
978 <tr>
979 <th>Initial:
980 <td>see individual properties
981 <tr>
982 <th>Applies To:
983 <td>all elements, ::before and ::after pseudo-elements
984 <tr>
985 <th>Inherited:
986 <td>see individual properties
987 <tr>
988 <th>Animatable:
989 <td>no
990 <tr>
991 <th>Percentages:
992 <td>N/A
993 <tr>
994 <th>Media:
995 <td>visual
996 <tr>
997 <th>Computed Value:
998 <td>see individual properties
999 <tr>
1000 <th>Canonical Order:
1001 <td><abbr title="follows order of property value definition">per grammar</abbr>
1002 </table>
1004 <div class="prod">
1005 <dfn id="single-animation"><single-animation></dfn> =
1006 <single-animation-name> ||
1007 <span><time></span> ||
1008 <single-animation-timing-function> ||
1009 <span><time></span> ||
1010 <single-animation-iteration-count> ||
1011 <single-animation-direction> ||
1012 <single-animation-fill-mode> ||
1013 <single-animation-play-state>
1014 </div>
1016 <p>
1017 Note that order is important within each animation definition:
1018 the first value that can be parsed as a <var><time></var> is assigned to the
1019 animation-duration,
1020 and the second value that can be parsed as a <var><time></var> is assigned to
1021 animation-delay.
1022 </p>
1024 <p class="issue">
1025 An alternative proposal is to accept the font shorthand approach
1026 of using a "/" character between the values of the same type.
1027 e.g. 2s/4s would mean a duration of 2 seconds and a delay of 4 seconds.
1029 <p class="issue">
1030 Need to also explain how order is important in terms of animation-name
1031 versus keywords, and probably also adjust the canonical order to
1032 match.
1034 <h2 id="animation-events">
1035 Animation Events</h2>
1037 <p>
1038 Several animation related events are available through the <a href="http://www.w3.org/TR/DOM-Level-2-Events/events.html">DOM Event system</a>.
1039 The start and end of an animation,
1040 and the end of each iteration of an animation,
1041 all generate DOM events.
1042 An element can have multiple properties being animated simultaneously.
1043 This can occur either with a single 'animation-name' value
1044 with keyframes containing multiple properties,
1045 or with multiple 'animation-name' values.
1046 For the purposes of events,
1047 each 'animation-name' specifies a single animation.
1048 Therefore an event will be generated for each 'animation-name' value
1049 and not necessarily for each property being animated.
1051 <p>
1052 Any animation for which both a valid keyframe rule and a non-zero duration are
1053 defined will run and generate events; this includes animations with empty
1054 keyframe rules.
1056 <p>
1057 The time the animation has been running is sent with each event generated.
1058 This allows the event handler to determine the current iteration of a looping animation
1059 or the current position of an alternating animation.
1060 This time does not include any time the animation was in the ''paused'' play state.
1063 <h3 id='AnimationEvent-interface'>
1064 Interface <code>AnimationEvent</code>
1066 <p>
1067 The <dfn>AnimationEvent</dfn> interface provides specific contextual information associated with Animation events.
1070 <h4 id='AnimationEvent-IDL'>
1071 IDL Definition</h4>
1073 <pre class='idl'>
1074 [Constructor(DOMString <var title="">type</var>, optional <a href="#AnimationEventInit">AnimationEventInit</a> <var title="">eventInitDict</var>)]
1075 interface AnimationEvent : <a class="external" href="http://dvcs.w3.org/hg/domcore/raw-file/tip/Overview.html#event">Event</a> {
1076 readonly attribute DOMString <a href="#AnimationEvent-animationName" title="AnimationEvent-lengthComputable">animationName</a>;
1077 readonly attribute float <a href="#AnimationEvent-elapsedTime" title="dom-ProgressEvent-loaded">elapsedTime</a>;
1078 readonly attribute DOMString <a href="#AnimationEvent-pseudoElement" title="AnimationEvent-pseudoElement">pseudoElement</a>;
1079 };
1081 dictionary AnimationEventInit : <a class="external" href="http://dvcs.w3.org/hg/domcore/raw-file/tip/Overview.html#eventinit">EventInit</a> {
1082 DOMString <span title="AnimationEventInit-animationName">animationName</span>;
1083 float <span title="AnimationEventInit-loaded">elapsedTime</span>;
1084 DOMString <span title="AnimationEventInit-pseudoElement">pseudoElement</span>;
1085 }
1087 </pre>
1090 <h4 id='AnimationEvent-attributes'>
1091 Attributes</h4>
1093 <dl>
1094 <dt><code><dfn id='AnimationEvent-animationName'>animationName</dfn></code> of type <code>DOMString</code>, readonly
1095 <dd>
1096 The value of the 'animation-name' property of the animation that fired the event.
1098 <dt><code><dfn id='AnimationEvent-elapsedTime'>elapsedTime</dfn></code> of type <code>float</code>, readonly
1099 <dd>
1100 The amount of time the animation has been running,
1101 in seconds,
1102 when this event fired,
1103 excluding any time the animation was paused.
1104 For an "animationstart" event,
1105 the elapsedTime is zero unless there was a negative value for 'animation-delay',
1106 in which case the event will be fired with an <code>elapsedTime</code> of (-1 * delay).
1108 <dt><code><dfn id='AnimationEvent-pseudoElement'>pseudoElement</dfn></code> of type <code>DOMString</code>, readonly
1109 <dd>
1110 The name (beginning with two colons) of the CSS pseudo-element on
1111 which the animation runs (in which case the target of the event
1112 is that pseudo-element's corresponding element), or the empty string
1113 if the animation runs on an element (which means the target of the event
1114 is that element).
1115 </dl>
1117 <p>
1118 <code id="AnimationEvent-constructor">AnimationEvent(type, animEventDict)</code>
1119 is an <a class="external" href="http://dvcs.w3.org/hg/domcore/raw-file/tip/Overview.html#concept-event-constructor">event constructor</a>.
1121 <h3 id='AnimationEvent-types'>
1122 Types of <code>AnimationEvent</code></h3>
1124 <p>
1125 The different types of Animation events that can occur are:
1127 <dl>
1128 <dt><dfn>animationstart</dfn>
1129 <dd>
1130 The <code>animationstart</code> event occurs at the start of the animation.
1131 If there is an 'animation-delay'
1132 then this event will fire once the delay period has expired.
1133 A negative delay will cause the event to fire with an <code>elapsedTime</code> equal to the absolute value of the delay.
1135 <ul>
1136 <li>Bubbles: Yes
1137 <li>Cancelable: No
1138 <li>Context Info: animationName
1139 </ul>
1141 <dt><dfn>animationend</dfn>
1142 <dd>
1143 The <code>animationend</code> event occurs when the animation finishes.
1145 <ul>
1146 <li>Bubbles: Yes
1147 <li>Cancelable: No
1148 <li>Context Info: animationName, elapsedTime
1149 </ul>
1151 <dt><dfn>animationiteration</dfn>
1152 <dd>
1153 The <code>animationiteration</code> event occurs at the end of each iteration of an animation,
1154 except when an <code>animationend</code> event would fire at the same time.
1155 This means that this event does not occur for animations with an iteration count of one or less.
1157 <ul>
1158 <li>Bubbles: Yes
1159 <li>Cancelable: No
1160 <li>Context Info: animationName, elapsedTime
1161 </ul>
1162 </dl>
1165 <h2 id="dom-interfaces">
1166 DOM Interfaces</h2>
1168 <p>
1169 CSS animation is exposed to the CSSOM through a pair of new interfaces describing the keyframes.
1172 <h3 id='CSSRule-interface'>
1173 Interface <code>CSSRule</code></h3>
1175 <p>
1176 The following 2 rule types are added to the <dfn>CSSRule</dfn> interface.
1177 They provide identification for the new keyframe and keyframes rules.
1180 <h4 id='CSSRule-IDL'>
1181 IDL Definition</h4>
1183 <pre class='idl'>
1184 interface CSSRule {
1185 ...
1186 const unsigned short KEYFRAMES_RULE = 7;
1187 const unsigned short KEYFRAME_RULE = 8;
1188 ...
1189 };</pre>
1192 <h3 id='CSSKeyframeRule-interface'>
1193 Interface <code>CSSKeyframeRule</code></3h>
1194 <p>
1195 The <dfn>CSSKeyframeRule</dfn> interface represents the style rule for a single key.
1198 <h4 id='CSSKeyframeRule-IDL'>
1199 IDL Definition</h4>
1201 <pre class='idl'>
1202 interface CSSKeyframeRule : CSSRule {
1203 attribute DOMString keyText;
1204 readonly attribute CSSStyleDeclaration style;
1205 };</pre>
1208 <h4 id='CSSKeyframeRule-attributes'>
1209 Attributes</h4>
1211 <dl>
1212 <dt><code><dfn id='CSSKeyframeRule-keyText'>keyText</dfn></code> of type <code>DOMString</code>
1213 <dd>
1214 This attribute represents the keyframe selector as a comma-separated
1215 list of percentage values. The ''from'' and ''to'' keywords map to
1216 ''0%'' and ''100%'', respectively.
1218 <dt><code><dfn id='CSSKeyframeRule-style'>style</dfn></code> of type <code>CSSStyleDeclaration</code>
1219 <dd>
1220 This attribute represents the style associated with this keyframe.
1221 </dl>
1224 <h3 id='CSSKeyframesRule-interface'>
1225 Interface <code>CSSKeyframesRule</code></h3>
1227 <p>
1228 The <dfn>CSSKeyframesRule</dfn> interface represents a complete set of keyframes for a single animation.
1231 <h4 id='CSSKeyframesRule-IDL'>
1232 IDL Definition</h4>
1234 <pre class='idl'>
1235 interface CSSKeyframesRule : CSSRule {
1236 attribute DOMString name;
1237 readonly attribute CSSRuleList cssRules;
1239 void appendRule(in DOMString rule);
1240 void deleteRule(in DOMString key);
1241 CSSKeyframeRule findRule(in DOMString key);
1242 };</pre>
1245 <h4 id='CSSKeyframesRule-attributes'>
1246 Attributes</h4>
1248 <dl>
1249 <dt><code><dfn id='CSSKeyframesRule-name'>name</dfn></code> of type <code>DOMString</code>
1250 <dd>
1251 This attribute is the name of the keyframes, used by the 'animation-name' property.<br>
1253 <dt><code><dfn id='CSSKeyframesRules-cssRules'>cssRules</dfn></code> of type <code>CSSRuleList</code>
1254 <dd>
1255 This attribute gives access to the keyframes in the list.
1258 <h4 id='CSSKeyframesRule-appendRule'>
1259 The <code>appendRule</code> method</h4>
1261 <p>
1262 The <dfn>appendRule</dfn> method appends the passed CSSKeyframeRule into the list at the passed key.
1264 <p>
1265 Parameters:
1267 <dl>
1268 <dt><code>rule</code> of type <code>DOMString</code>
1270 <dd>
1271 The rule to be appended,
1272 expressed in the same syntax as one entry in the ''@keyframes'' rule.
1273 </dl>
1275 <p>
1276 No Return Value
1278 <p>
1279 No Exceptions
1282 <h4 id='CSSKeyframesRules-deleteRule'>
1283 The <code>deleteRule</code> method</h4>
1285 <p>
1286 The <dfn>deleteRule</dfn> method deletes the CSSKeyframeRule with the passed key.
1287 If a rule with this key does not exist,
1288 the method does nothing.
1290 <p>
1291 Parameters:
1293 <dl>
1294 <dt><code>key</code> of type <code>DOMString</code>
1295 <dd>
1296 The key which describes the rule to be deleted.
1297 The key must resolve to a number between 0 and 1,
1298 or the rule is ignored.
1299 </dl>
1301 <p>
1302 No Return Value
1304 <p>
1305 No Exceptions
1308 <h4 id='CSSKeyframesRule-findRule'>
1309 The <code>findRule</code> method</h4>
1311 <p>
1312 The <code>findRule</code> method returns the rule with a key matching the passed key.
1313 If no such rule exists,
1314 a null value is returned.
1316 <p>
1317 Parameters:
1319 <dl>
1320 <dt><code>key</code> of type <code>DOMString</code>
1321 <dd>
1322 The key which described the rule to find.
1323 The key must resolve to a number between 0 and 1,
1324 or the rule is ignored.
1325 </dl>
1327 <p>
1328 Return Value:
1330 <dl>
1331 <dt><code>CSSKeyframeRule</code>
1332 <dd>
1333 The found rule.
1334 </dl>
1336 <p>
1337 No Exceptions
1340 <h2 id="acknowledgments">Acknowledgments</h2>
1342 <p>Thanks especially to the feedback from
1343 Tab Atkins,
1344 Carine Bournez,
1345 Estelle Weyl,
1346 and all the rest of the
1347 <a href="http://lists.w3.org/Archives/Public/www-style/">www-style</a> community.
1349 <h2>References</h2>
1351 <h3 class="no-num">Normative references</h3>
1352 <!--normative-->
1354 <h3 class="no-num">Other references</h3>
1355 <!--informative-->
1359 <h2 class="no-num">Property index</h2>
1360 <!-- properties -->
1364 <h2 class="no-num" id="index">Index</h2>
1365 <!--index-->
1367 </body>
1368 </html>
1369 <!-- Keep this comment at the end of the file
1370 Local variables:
1371 mode: sgml
1372 sgml-declaration:"~/SGML/HTML4.decl"
1373 sgml-default-doctype-name:"html"
1374 sgml-minimize-attributes:t
1375 sgml-nofill-elements:("pre" "style" "br")
1376 sgml-live-element-indicator:t
1377 sgml-omittag:nil
1378 sgml-shorttag:nil
1379 sgml-namecase-general:t
1380 sgml-general-insert-case:lower
1381 sgml-always-quote-attributes:t
1382 sgml-indent-step:nil
1383 sgml-indent-data:t
1384 sgml-parent-document:nil
1385 sgml-exposed-tags:nil
1386 sgml-local-catalogs:nil
1387 sgml-local-ecat-files:nil
1388 End:
1389 -->
