Thu, 28 Jun 2012 11:44:32 -0700
Fix the definition of 'animation-fill-mode' as described in http://lists.w3.org/Archives/Public/www-style/2012Jun/0447.html .
1. account for 'reverse' and 'alternate-reverse' animation directions
2. account for the possibility that 'animation-iteration-count' is not an integer
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 </head>
10 <body>
12 <div class="head">
13 <!--logo-->
15 <h1>CSS Animations</h1>
17 <h2 class="no-num no-toc">[LONGSTATUS] [DATE]</h2>
18 <dl>
19 <dt>This version:
20 <dd><a href="[VERSION]">http://dev.w3.org/csswg/css3-animations/</a>
21 <!--http://www.w3.org/TR/[YEAR]/WD-[SHORTNAME]-[CDATE]/-->
22 <dt>Latest version:
23 <dd><a
24 href="http://www.w3.org/TR/css3-animations/">[LATEST]</a>
25 <dt>Editor's draft:
26 <dd><a href="http://dev.w3.org/csswg/[SHORTNAME]/">http://dev.w3.org/csswg/[SHORTNAME]/</a>
28 <dt>Previous version:
29 <dd><a href="http://www.w3.org/TR/2012/WD-css3-animations-20120403/">
30 http://www.w3.org/TR/2012/WD-css3-animations-20120403/</a>
31 <dt id="editors-list">Editors:
32 <dd><a href="mailto:dino@apple.com">Dean Jackson</a> (<a
33 href="http://www.apple.com/">Apple Inc</a>)
34 <dd><a href="mailto:hyatt@apple.com">David Hyatt</a> (<a
35 href="http://www.apple.com/">Apple Inc</a>)
36 <dd><a href="mailto:cmarrin@apple.com">Chris Marrin</a> (<a
37 href="http://www.apple.com/">Apple Inc</a>)
38 <dd><a href="mailto:sylvaing@microsoft.com">Sylvain Galineau</a>
39 (<a class=org href="http://www.microsoft.com/">Microsoft</a>)
40 <dd class=vcard><a class=fn href="http://dbaron.org/">L. David Baron</a>
41 (<a class=org href="http://www.mozilla.org/">Mozilla</a>)
43 <dt>Issues list:
44 <dd><a href="https://www.w3.org/Bugs/Public/buglist.cgi?query_format=advanced&product=CSS&component=Animations&resolution=---&cmdtype=doit">in Bugzilla</a>
46 <dt>Discussion:
47 <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>”
49 <dt>Test suite:
50 <dd>none yet
51 </dl>
53 <!--copyright-->
55 <hr title="Separator for header">
56 </div>
58 <h2 class="no-num no-toc" id="abstract">
59 Abstract</h2>
61 <p>
62 This CSS module describes a way for authors to animate the values of CSS properties over time,
63 using keyframes.
64 The behavior of these keyframe animations can be controlled by specifying their duration,
65 number of repeats,
66 and repeating behavior.
69 <h2 class="no-num no-toc" id="status">
70 Status of this document</h2>
71 <!--status-->
74 <h2 class="no-num no-toc" id="contents">
75 Table of contents</h2>
76 <!--toc-->
79 <h2 id="introduction">
80 Introduction</h2>
82 <p><em>This section is not normative.</em>
84 <p>
85 CSS Transitions [[CSS3-TRANSITIONS]]
86 provide a way to interpolate CSS property values
87 when they change as a result of underlying property changes.
88 This provides an easy way to do simple animation,
89 but the start and end states of the animation are controlled by the existing property values,
90 and transitions provide little control to the author on how the animation progresses.
92 <p>
93 This proposal introduces <dfn>defined animations</dfn>,
94 in which the author can specify the changes in CSS properties over time as a set of keyframes.
95 Animations are similar to transitions
96 in that they change the presentational value of CSS properties over time.
97 The principal difference is that
98 while transitions trigger <em>implicitly</em> when property values change,
99 animations are <em>explicitly</em> executed when the animation properties are applied.
100 Because of this,
101 animations require explicit values for the properties being animated.
102 These values are specified using animation keyframes, described below.
104 <p>
105 Many aspects of the animation can be controlled,
106 including how many times the animation iterates,
107 whether or not it alternates between the begin and end values,
108 and whether or not the animation should be running or paused.
109 An animation can also delay its start time.
112 <h2 id="animations">
113 Animations</h2>
115 <p>
116 CSS Animations affect computed property values.
117 During the execution of an animation,
118 the computed value for a property is controlled by the animation.
119 This overrides the value specified in the normal styling system.
122 <p>
123 If at one point in time there are multiple animations specifying behavior for the same property,
124 the animation whose name occurs last in the value of 'animation-name'
125 will override the other animations at that point.
128 <p>
129 An animation does not affect the computed value before the application of the animation,
130 before the animation delay has expired,
131 and after the end of the animation.
134 <div class="figure">
135 <img src="sandwich.png" alt="">
137 <p class="caption">
138 Computation of animated property values
139 </div>
141 <p>
142 The diagram above shows how property values are computed.
143 The intrinsic style is shown at the top of the diagram.
144 The computed value is derived from intrinsic style
145 at the times when an animation is not running
146 and also when an animation is delayed
147 (see below for specification of animation delay).
148 During an animation,
149 the computed style is derived from the animated value.
152 <p>
153 The start time of an animation is the latter of two moments:
154 the time at which the style is resolved that specifies the animation,
155 or the time the document's load event is fired.
156 Therefore, an animation specified in the document style sheet
157 will begin at the document load.
158 An animation specified on an element by modifying the style after the document has loaded
159 will start when the style is resolved.
160 That may be immediately in the case of a pseudo style rule such as hover,
161 or may be when the scripting engine returns control to the browser
162 (in the case of style applied by script).
165 <p>
166 An animation applies to an element
167 if the element has a value for 'animation-name' that references a valid keyframes rule.
168 Once an animation has started
169 it continues until it ends
170 or the 'animation-name' is removed.
171 The values used for the keyframes and animation properties are snapshotted at the time the animation starts.
172 Changing them during the execution of the animation has no effect.
173 Note also that changing the value of 'animation-name' does not necessarily restart an animation
174 (e.g., if a list of animations are applied and one is removed from the list,
175 only that animation will stop;
176 The other animations will continue).
177 In order to restart an animation,
178 it must be removed then reapplied.
181 <p>
182 The end of the animation is defined by the combination of the
183 'animation-duration',
184 'animation-iteration-count' and
185 'animation-fill-mode' properties.
188 <div class="example">
189 <pre>
190 div {
191 animation-name: diagonal-slide;
192 animation-duration: 5s;
193 animation-iteration-count: 10;
194 }
196 @keyframes diagonal-slide {
198 from {
199 left: 0;
200 top: 0;
201 }
203 to {
204 left: 100px;
205 top: 100px;
206 }
208 }</pre>
210 <p>
211 This will produce an animation
212 that moves an element from (0, 0) to (100px, 100px)
213 over five seconds
214 and repeats itself nine times
215 (for a total of ten iterations).
216 </div>
218 <h2 id="keyframes">
219 Keyframes</h2>
220 <p>
221 Keyframes are used to specify the values for the animating properties
222 at various points during the animation.
223 The keyframes specify the behavior of one cycle of the animation;
224 the animation may iterate one or more times.
226 <p>
227 Keyframes are specified using a specialized CSS at-rule.
228 A @keyframes rule consists of the keyword "@keyframes",
229 followed by an identifier giving a name for the animation
230 (which will be referenced using 'animation-name'),
231 followed by a set of style rules
232 (delimited by curly braces).
234 <p>
235 The <dfn>keyframe selector</dfn> for a keyframe style rule
236 consists of a comma-separated list of percentage values
237 or the keywords 'from' or 'to'.
238 The selector is used to specify the percentage along the duration of the animation that the keyframe represents.
239 The keyframe itself is specified by the block of property values declared on the selector.
240 The keyword 'from' is equivalent to the value ''0%''.
241 The keyword 'to' is equivalent to the value ''100%''.
242 <span class='note'>Note that the percentage unit specifier must be used on percentage values.
243 Therefore, ''0'' is an invalid keyframe selector.</span>
245 <p>
246 If a ''0%'' or ''from'' keyframe is not specified,
247 then the user agent constructs a ''0%'' keyframe
248 using the computed values of the properties being animated.
249 If a ''100%'' or ''to'' keyframe is not specified,
250 then the user agent constructs a ''100%'' keyframe
251 using the computed values of the properties being animated.
253 <p>
254 The <dfn>keyframe declaration</dfn> for a keyframe rule
255 consists of properties and values.
256 Properties that are unable to be animated are ignored in these rules,
257 with the exception of 'animation-timing-function',
258 the behavior of which is described below.
260 <p class="issue">
261 Need to describe what happens if a property is not present in all keyframes.
263 <p>
264 The @keyframes rule that is used by an animation
265 will be the last one encountered in sorted rules order
266 that matches the name of the animation specified by the 'animation-name' property.
267 @keyframes rules do not cascade;
268 therefore, an animation will never derive keyframes from more than one @keyframes rule.
270 <p>
271 To determine the set of keyframes,
272 all of the values in the selectors are sorted in increasing order by time.
273 If there are any duplicates,
274 then the last keyframe specified inside the @keyframes rule
275 will be used to provide the keyframe information for that time.
276 There is no cascading within a @keyframes rule if multiple keyframes specify the same keyframe selector values.
278 <p>
279 If a property is not specified for a keyframe,
280 or is specified but invalid,
281 the animation of that property proceeds as if that keyframe did not exist.
282 Conceptually,
283 it is as if a set of keyframes is constructed for each property that is present in any of the keyframes,
284 and an animation is run independently for each property.
286 <div class="example">
287 <pre>
288 @keyframes wobble {
289 0% {
290 left: 100px;
291 }
293 40% {
294 left: 150px;
295 }
297 60% {
298 left: 75px;
299 }
301 100% {
302 left: 100px;
303 }
304 }</pre>
306 <p>
307 Four keyframes are specified for the animation named "wobble".
308 In the first keyframe,
309 shown at the beginning of the animation cycle,
310 the value of the 'left' property being animated is ''100px''.
311 By 40% of the animation duration,
312 'left' has animated to ''150px''.
313 At 60% of the animation duration,
314 'left' has animated back to ''75px''.
315 At the end of the animation cycle,
316 the value of 'left' has returned to ''100px''.
317 The diagram below shows the state of the animation if it were given a duration of ''10s''.
319 <div class="figure">
320 <img src="animation1.png" alt="">
322 <p class="caption">
323 Animations states specified by keyframes
324 </div>
325 </div>
327 <p>
328 The following is the grammar for the keyframes rule.
330 <pre>
331 keyframes_rule: KEYFRAMES_SYM S+ IDENT S* '{' S* keyframes_blocks '}' S*;
333 keyframes_blocks: [ keyframe_selector '{' S* declaration? [ ';' S* declaration? ]* '}' S* ]* ;
335 keyframe_selector: [ FROM_SYM | TO_SYM | PERCENTAGE ] S* [ ',' S* [ FROM_SYM | TO_SYM | PERCENTAGE ] S* ]*;
337 @{K}{E}{Y}{F}{R}{A}{M}{E}{S} {return KEYFRAMES_SYM;}
338 {F}{R}{O}{M} {return FROM_SYM;}
339 {T}{O} {return TO_SYM;}</pre>
342 <h3 id="timing-functions">
343 Timing functions for keyframes</h3>
345 <p>
346 A keyframe style rule may also declare the timing function that is to be used
347 as the animation moves to the next keyframe.
349 <div class="example">
350 <pre>
351 @keyframes bounce {
353 from {
354 top: 100px;
355 animation-timing-function: ease-out;
356 }
358 25% {
359 top: 50px;
360 animation-timing-function: ease-in;
361 }
363 50% {
364 top: 100px;
365 animation-timing-function: ease-out;
366 }
368 75% {
369 top: 75px;
370 animation-timing-function: ease-in;
371 }
373 to {
374 top: 100px;
375 }
377 }</pre>
379 <p>
380 Five keyframes are specified for the animation named "bounce".
381 Between the first and second keyframe
382 (i.e., between 0% and 25%)
383 an ''ease-out'' timing function is used.
384 Between the second and third keyframe
385 (i.e., between 25% and 50%)
386 an ''ease-in'' timing function is used.
387 And so on.
388 The effect will appear as an element that moves up the page ''50px'',
389 slowing down as it reaches its highest point
390 then speeding up as it falls back to ''100px''.
391 The second half of the animation behaves in a similar manner,
392 but only moves the element ''25px'' up the page.
393 </div>
395 <p>
396 A timing function specified on the "to" or 100% keyframe is ignored.
398 <p>
399 See the 'animation-timing-function' property for more information.
402 <h3 id="animation-name-property">
403 The 'animation-name' Property</h3>
405 <p>
406 The 'animation-name' property defines a list of animations that apply.
407 Each name is used to select the keyframe at-rule
408 that provides the property values for the animation.
409 If the name does not match any keyframe at-rule,
410 there are no properties to be animated
411 and the animation will not execute.
412 Furthermore,
413 if the animation name is ''none''
414 then there will be no animation.
415 This can be used to override any animations coming from the cascade.
416 If multiple animations are attempting to modify the same property,
417 then the animation closest to the end of the list of names wins.
419 <p id="list-matching">
420 Each animation listed by name
421 should have a corresponding value for the other animation properties listed below.
422 If the lists of values for the other animation properties do not have the same length,
423 the length of the 'animation-name' list
424 determines the number of items in each list examined when starting transitions.
425 The lists are matched up from the first value:
426 excess values at the end are not used.
427 If one of the other properties doesn't have enough comma-separated values to match the number of values of 'animation-name',
428 the UA must calculate its used value by repeating the list of values until there are enough.
429 This truncation or repetition does not affect the computed value.
430 <span class="note">Note: This is analogous to the behavior of the 'background-*'properties,
431 with 'background-image' analogous to 'animation-name'.</span>
434 <table class=propdef>
435 <tr>
436 <th>Name:</th>
437 <td><dfn>animation-name</dfn>
438 <tr>
439 <th><a href="#values">Value</a>:
440 <td>[ none | <user-ident> ]#
441 <tr>
442 <th>Initial:
443 <td>''none''
444 <tr>
445 <th>Applies To:
446 <td>all elements
447 <tr>
448 <th>Inherited:
449 <td>no
450 <tr>
451 <th>Computed Value:
452 <td>As specified
453 <tr>
454 <th>Media:
455 <td>visual
456 <tr>
457 <th>Animatable:
458 <td>no
459 <tr>
460 <th>Canonical Order:
461 <td><abbr title="follows order of property value definition">per grammar</abbr>
462 </table>
464 <!--
465 <p>
466 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.
468 <div class="example">
469 <p style="display:none">
470 Example(s):
472 <pre>
473 @keyframes 'border-bloat' {
474 from {
475 border-width: 0;
476 }
477 to {
478 border-width: 10px;
479 }
480 }
482 @keyframes 'border-diet' {
483 from {
484 border-width: 4px;
485 }
486 to {
487 border-width: 2px;
488 }
489 }
491 div {
492 animation-name: 'border-bloat', 'border-diet';
493 animation-duration: 10s, 4s;
494 }
495 </pre>
496 <p>
497 The above example has two animations executing on the same property, 'border-width'. The animations are additive. That is, the
498 resulting value for the property will be the addition of the values from the
499 two animations.
501 <p>
502 At time '0s' the element's border will be 4px wide (0px from 'border-bloat' plus 4px from 'border-diet').
503 At time '4s' the element's border will be 6px wide (4px from 'border-bloat' plus 2px from 'border-diet').
504 At time '10s' the element's border will be 10px wide (10px from 'border-bloat' and no addition from
505 'border-diet' as it is no longer executing).
507 </div>
508 -->
511 <h3 id="animation-duration-property">
512 The 'animation-duration' Property</h3>
514 <p>
515 The 'animation-duration' property defines the length of time that an animation takes to complete one cycle.
518 <table class=propdef>
519 <tr>
520 <th>Name:</th>
521 <td><dfn>animation-duration</dfn>
522 <tr>
523 <th><a href="#values">Value</a>:
524 <td><time>#
525 <tr>
526 <th>Initial:
527 <td>''0s''
528 <tr>
529 <th>Applies To:
530 <td>all elements
531 <tr>
532 <th>Inherited:
533 <td>no
534 <tr>
535 <th>Computed Value:
536 <td>as specified
537 <tr>
538 <th>Media:
539 <td>visual
540 <tr>
541 <th>Animatable:
542 <td>no
543 <tr>
544 <th>Canonical Order:
545 <td><abbr title="follows order of property value definition">per grammar</abbr>
546 </table>
548 <p>
549 The initial value is ''0s'',
550 meaning that the animation takes no time.
551 A negative value for 'animation-duration' is treated as ''0s''.
552 In this case 'animation-fill-mode' still applies,
553 so an animation that fills backwards
554 will show the value of the 0% keyframe during any delay period,
555 and an animation that fills forwards will retain the value specified at the 100% keyframe,
556 even if the animation was instantaneous.
557 Also, animation events are still fired.
560 <h3 id="animation-timing-function-property">
561 The 'animation-timing-function' Property</h3>
563 <p>
564 The 'animation-timing-function' property describes how the animation will progress over one cycle of its duration.
565 See the 'transition-timing-function' property [[!CSS3-TRANSITIONS]] for a complete description of timing function calculation.
567 <table class=propdef>
568 <tr>
569 <th>Name:</th>
570 <td><dfn>animation-timing-function</dfn>
571 <tr>
572 <th><a href="#values">Value</a>:
573 <td>[
574 ease | linear | ease-in | ease-out | ease-in-out |
575 step-start | step-end |
576 steps(<number> [, [ start | end ] ]) |
577 cubic-bezier(<number>, <number>, <number>, <number>)
578 ]#
579 <tr>
580 <th>Initial:
581 <td>''ease''
582 <tr>
583 <th>Applies To:
584 <td>all elements
585 <tr>
586 <th>Inherited:
587 <td>no
588 <tr>
589 <th>Computed Value:
590 <td>as specified
591 <tr>
592 <th>Media:
593 <td>visual
594 <tr>
595 <th>Animatable:
596 <td>no
597 <tr>
598 <th>Canonical Order:
599 <td><abbr title="follows order of property value definition">per grammar</abbr>
600 </table>
602 <p>
603 For a keyframed animation,
604 the 'animation-timing-function' applies between keyframes,
605 not over the entire animation.
606 For example,
607 in the case of an ''ease-in-out'' timing function,
608 an animation will ease in at the start of the keyframe
609 and ease out at the end of the keyframe.
610 An 'animation-timing-function' defined within a keyframe block applies to that keyframe,
611 otherwise the timing function specified for the animation is used.
614 <h3 id="animation-iteration-count-property">
615 The 'animation-iteration-count' Property</h3>
617 <p>
618 The 'animation-iteration-count' property specifies the number of times an animation cycle is played.
619 The initial value is ''1'',
620 meaning the animation will play from beginning to end once.
621 A value of ''infinite'' will cause the animation to repeat forever.
622 Non-integer numbers will cause the animation to end part-way through a cycle.
623 Negative values of 'animation-iteration-count' are invalid.
624 This property is often used in conjunction an 'animation-direction' value of ''alternate'',
625 which will cause the animation to play in reverse on alternate cycles.
627 <table class=propdef>
628 <tr>
629 <th>Name:</th>
630 <td><dfn>animation-iteration-count</dfn>
631 <tr>
632 <th><a href="#values">Value</a>:
633 <td>[ infinite | <number> ]#
634 <tr>
635 <th>Initial:
636 <td>''1''
637 <tr>
638 <th>Applies To:
639 <td>all elements
640 <tr>
641 <th>Inherited:
642 <td>no
643 <tr>
644 <th>Computed Value:
645 <td>as specified
646 <tr>
647 <th>Media:
648 <td>visual
649 <tr>
650 <th>Animatable:
651 <td>no
652 <tr>
653 <th>Canonical Order:
654 <td><abbr title="follows order of property value definition">per grammar</abbr>
655 </table>
658 <h3 id="animation-direction-property">
659 The 'animation-direction' Property</h3>
661 <p>
662 The 'animation-direction' property defines whether or not the animation should play in reverse on some or all cycles.
663 When an animation is played in reverse the timing functions are also reversed.
664 For example, when played in reverse an ease-in animation would appear to be an ease-out animation.
666 <table class=propdef>
667 <tr>
668 <th>Name:</th>
669 <td><dfn>animation-direction</dfn>
670 <tr>
671 <th><a href="#values">Value</a>:
672 <td>[ normal | reverse | alternate | alternate-reverse ]#
673 <tr>
674 <th>Initial:
675 <td>''normal''
676 <tr>
677 <th>Applies To:
678 <td>all elements
679 <tr>
680 <th>Inherited:
681 <td>no
682 <tr>
683 <th>Computed Value:
684 <td>as specified
685 <tr>
686 <th>Media:
687 <td>visual
688 <tr>
689 <th>Animatable:
690 <td>no
691 <tr>
692 <th>Canonical Order:
693 <td><abbr title="follows order of property value definition">per grammar</abbr>
694 </table>
696 <dl>
697 <dt><dfn>normal</dfn>
698 <dd>
699 All iterations of the animation are played as specified.
701 <dt><dfn>reverse</dfn>
702 <dd>
703 All iterations of the animation are played in the reverse direction from the way they were specified.
705 <dt><dfn>alternate</dfn>
706 <dd>
707 The animation cycle iterations that are odd counts are played in the normal direction,
708 and the animation cycle iterations that are even counts are played in a reverse direction.
710 <dt><dfn>alternate-reverse</dfn>
711 <dd>
712 The animation cycle iterations that are odd counts are played in the reverse direction,
713 and the animation cycle iterations that are even counts are played in a normal direction.
714 </dl>
716 <p class='note'>
717 Note that for the purpose of determining whether an iteration is even or odd,
718 iterations start counting from 1.
721 <h3 id="animation-play-state-property">
722 The 'animation-play-state' Property</h3>
724 <p>
725 The 'animation-play-state' property defines whether the animation is running or paused.
726 A running animation can be paused by setting this property to ''paused''.
727 To continue running a paused animation this property can be set to ''running''.
728 A paused animation will continue to display the current value of the animation in a static state,
729 as if the time of the animation is constant.
730 When a paused animation is resumed,
731 it restarts from the current value,
732 not necessarily from the beginning of the animation.
734 <table class=propdef>
735 <tr>
736 <th>Name:</th>
737 <td><dfn>animation-play-state</dfn>
738 <tr>
739 <th><a href="#values">Value</a>:
740 <td>[ running | paused ]#
741 <tr>
742 <th>Initial:
743 <td>''running''
744 <tr>
745 <th>Applies To:
746 <td>all elements
747 <tr>
748 <th>Inherited:
749 <td>no
750 <tr>
751 <th>Computed Value:
752 <td>as specified
753 <tr>
754 <th>Media:
755 <td>visual
756 <tr>
757 <th>Animatable:
758 <td>no
759 <tr>
760 <th>Canonical Order:
761 <td><abbr title="follows order of property value definition">per grammar</abbr>
762 </table>
765 <h3 id="animation-delay-property">
766 The 'animation-delay' Property</h3>
768 <p>
769 The 'animation-delay' property defines when the animation will start.
770 It allows an animation to begin execution some time after it is applied.
771 An 'animation-delay' value of ''0s'' means the animation will execute as soon as it is applied.
772 Otherwise, the value specifies an offset from the moment the animation is applied,
773 and the animation will delay execution by that offset.
775 <p>
776 If the value for 'animation-delay' is a negative time offset
777 then the animation will execute the moment it is applied,
778 but will appear to have begun execution at the specified offset.
779 That is, the animation will appear to begin part-way through its play cycle.
780 In the case where an animation has implied starting values and a negative 'animation-delay',
781 the starting values are taken from the moment the animation is applied.
783 <table class=propdef>
784 <tr>
785 <th>Name:</th>
786 <td><dfn>foo</dfn>
787 <tr>
788 <th><a href="#values">animation-delay</a>:
789 <td><time>#
790 <tr>
791 <th>Initial:
792 <td>''0s''
793 <tr>
794 <th>Applies To:
795 <td>all elements
796 <tr>
797 <th>Inherited:
798 <td>no
799 <tr>
800 <th>Computed Value:
801 <td>as specified
802 <tr>
803 <th>Media:
804 <td>visual
805 <tr>
806 <th>Animatable:
807 <td>no
808 <tr>
809 <th>Canonical Order:
810 <td><abbr title="follows order of property value definition">per grammar</abbr>
811 </table>
814 <h3 id="animation-fill-mode-property">
815 The 'animation-fill-mode' Property</h3>
817 <p>
818 The 'animation-fill-mode' property defines what values are applied by the animation outside the time it is executing.
819 By default, an animation will not affect property values
820 between the time it is applied
821 (the 'animation-name' property is set on an element)
822 and the time it begins execution
823 (which is determined by the 'animation-delay' property).
824 Also, by default an animation does not affect property values after the animation ends
825 (determined by the 'animation-duration' property).
826 The 'animation-fill-mode' property can override this behavior.
828 <p>
829 If the value for 'animation-fill-mode' is ''backwards'',
830 then the animation will apply
831 the property values defined in the keyframe
832 that will start the first iteration of the animation,
833 during the period defined by 'animation-delay'.
834 These are either the values of the ''from'' keyframe
835 (when 'animation-direction' is ''normal'' or ''alternate'')
836 or those of the ''to'' keyframe
837 (when 'animation-direction' is ''reverse'' or ''alternate-reverse'').
839 <p>
840 If the value for 'animation-fill-mode' is ''forwards'',
841 then after the animation ends
842 (as determined by its 'animation-iteration-count'),
843 the animation will apply
844 the property values for the time the animation ended.
845 When 'animation-iteration-count' is an integer greater than zero,
846 the values applied will be
847 those for the end of the last completed iteration of the animation
848 (rather than the values for
849 the start of the iteration that would be next).
850 When 'animation-iteration-count' is zero,
851 the values applied will be those that would start the first iteration
852 (just as when 'animation-fill-mode' is ''backwards'').
854 <p>
855 If the value for 'animation-fill-mode' is ''both'',
856 then the animation will follow the rules for both 'forwards' and 'backwards'.
857 That is, it will extend the animation properties in both directions.
859 <table class=propdef>
860 <tr>
861 <th>Name:</th>
862 <td><dfn>animation-fill-mode</dfn>
863 <tr>
864 <th><a href="#values">Value</a>:
865 <td>[ none | forwards | backwards | both ]#
866 <tr>
867 <th>Initial:
868 <td>''none''
869 <tr>
870 <th>Applies To:
871 <td>all elements
872 <tr>
873 <th>Inherited:
874 <td>no
875 <tr>
876 <th>Computed Value:
877 <td>as specified
878 <tr>
879 <th>Media:
880 <td>visual
881 <tr>
882 <th>Animatable:
883 <td>no
884 <tr>
885 <th>Canonical Order:
886 <td><abbr title="follows order of property value definition">per grammar</abbr>
887 </table>
890 <h3 id="animation-shorthand-property">
891 The 'animation' Shorthand Property
893 <p>
894 The 'animation' shorthand property combines seven of the animation properties into a single property.
896 <p>
897 Note that order is important in this property.
898 The first value that can be parsed as a <var><time></var> is assigned to the 'animation-duration'.
899 The second value that can be parsed as a <var><time></var> is assigned to 'animation-delay'.
901 <p class="issue">
902 An alternative proposal is to accept the font shorthand approach
903 of using a "/" character between the values of the same type.
904 e.g. 2s/4s would mean a duration of 2 seconds and a delay of 4 seconds.
906 <table class=propdef>
907 <tr>
908 <th>Name:</th>
909 <td><dfn>animation</dfn>
910 <tr>
911 <th><a href="#values">Value</a>:
912 <td>[ <'animation-name'> ||
913 <'animation-duration'> ||
914 <'animation-timing-function'> ||
915 <'animation-delay'> ||
916 <'animation-iteration-count'> ||
917 <'animation-direction'> ||
918 <'animation-fill-mode'> ]#
919 <tr>
920 <th>Initial:
921 <td>see individual properties
922 <tr>
923 <th>Applies To:
924 <td>all elements
925 <tr>
926 <th>Inherited:
927 <td>see individual properties
928 <tr>
929 <th>Computed Value:
930 <td>see individual properties
931 <tr>
932 <th>Media:
933 <td>visual
934 <tr>
935 <th>Animatable:
936 <td>no
937 <tr>
938 <th>Canonical Order:
939 <td><abbr title="follows order of property value definition">per grammar</abbr>
940 </table>
943 <h2 id="animation-events">
944 Animation Events</h2>
946 <p>
947 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>.
948 The start and end of an animation,
949 and the end of each iteration of an animation,
950 all generate DOM events.
951 An element can have multiple properties being animated simultaneously.
952 This can occur either with a single 'animation-name' value
953 with keyframes containing multiple properties,
954 or with multiple 'animation-name' values.
955 For the purposes of events,
956 each 'animation-name' specifies a single animation.
957 Therefore an event will be generated for each 'animation-name' value
958 and not necessarily for each property being animated.
960 <p>
961 The time the animation has been running is sent with each event generated.
962 This allows the event handler to determine the current iteration of a looping animation
963 or the current position of an alternating animation.
964 This time does not include any time the animation was in the ''paused'' play state.
967 <h3 id='AnimationEvent-interface'>
968 Interface <code>AnimationEvent</code>
970 <p>
971 The <dfn>AnimationEvent</dfn> interface provides specific contextual information associated with Animation events.
974 <h4 id='AnimationEvent-IDL'>
975 IDL Definition</h4>
977 <pre class='idl'>
978 interface AnimationEvent : Event {
979 readonly attribute DOMString animationName;
980 readonly attribute float elapsedTime;
981 void initAnimationEvent(in DOMString typeArg,
982 in boolean canBubbleArg,
983 in boolean cancelableArg,
984 in DOMString animationNameArg,
985 in float elapsedTimeArg);
986 };</pre>
989 <h4 id='AnimationEvent-attributes'>
990 Attributes</h4>
992 <dl>
993 <dt><code><dfn id='AnimationEvent-animationName'>animationName</dfn></code> of type <code>DOMString</code>, readonly
994 <dd>
995 The value of the 'animation-name' property of the animation that fired the event.
997 <dt><code><dfn id='AnimationEvent-elapsedTime'>elapsedTime</dfn></code> of type <code>float</code>, readonly
998 <dd>
999 The amount of time the animation has been running,
1000 in seconds,
1001 when this event fired,
1002 excluding any time the animation was paused.
1003 For an "animationstart" event,
1004 the elapsedTime is zero unless there was a negative value for 'animation-delay',
1005 in which case the event will be fired with an <code>elapsedTime</code> of (-1 * delay).
1006 </dl>
1009 <h4 id='AnimationEvent-initAnimationMethod'>
1010 The <code>initAnimationEvent</code> method</h4>
1012 <p>
1013 The <dfn>initAnimationEvent</dfn> method is used to initialize the value of an <code>AnimationEvent</code>
1014 created through the <a href='http://www.w3.org/TR/DOM-Level-2-Events/events.html#Events-DocumentEvent'><code>DocumentEvent</code></a> interface.
1015 This method may only be called before the <code>AnimationEvent</code> has been dispatched
1016 via the <code>dispatchEvent</code> method,
1017 though it may be called multiple times during that phase if necessary.
1018 If called multiple times,
1019 the final invocation takes precedence.
1021 <p>
1022 Parameters:
1024 <dl>
1025 <dt><code>typeArg</code> of type <code>DOMString</code>
1026 <dd>
1027 Specifies the event type.
1029 <dt><code>canBubbleArg</code> of type <code>boolean</code>
1030 <dd>
1031 Specifies whether or not the event can bubble.<br>
1033 <dt><code>cancelableArg</code> of type <code>boolean</code>
1034 <dd>
1035 Specifies whether or not the event's default action can be prevented.
1037 <dt><code>animationNameArg</code> of type <code>DOMString</code>
1038 <dd>
1039 Specifies the <a href='http://www.w3.org/TR/DOM-Level-2-Events/events.html#Events-Event'><code>Event</code></a>'s animation name.<br>
1041 <dt><code>elapsedTimeArg</code> of type <code>float</code>
1042 <dd>
1043 Specifies the amount of time,
1044 in seconds,
1045 the animation has been running at the time of initialization.
1046 </dl>
1048 <p>
1049 No Return Value
1051 <p>
1052 No Exceptions
1054 <h3 id='AnimationEvent-types'>
1055 Types of <code>AnimationEvent</code></h3>
1057 <p>
1058 The different types of Animation events that can occur are:
1060 <dl>
1061 <dt><dfn>animationstart</dfn>
1062 <dd>
1063 The <code>animationstart</code> event occurs at the start of the animation.
1064 If there is an 'animation-delay'
1065 then this event will fire once the delay period has expired.
1066 A negative delay will cause the event to fire with an <code>elapsedTime</code> equal to the absolute value of the delay.
1068 <ul>
1069 <li>Bubbles: Yes
1070 <li>Cancelable: No
1071 <li>Context Info: animationName
1072 </ul>
1074 <dt><dfn>animationend</dfn>
1075 <dd>
1076 The <code>animationend</code> event occurs when the animation finishes.
1078 <ul>
1079 <li>Bubbles: Yes
1080 <li>Cancelable: No
1081 <li>Context Info: animationName, elapsedTime
1082 </ul>
1084 <dt><dfn>animationiteration</dfn>
1085 <dd>
1086 The <code>animationiteration</code> event occurs at the end of each iteration of an animation,
1087 except when an <code>animationend</code> event would fire at the same time.
1088 This means that this event does not occur for animations with an iteration count of one or less.
1090 <ul>
1091 <li>Bubbles: Yes
1092 <li>Cancelable: No
1093 <li>Context Info: animationName, elapsedTime
1094 </ul>
1095 </dl>
1098 <h2 id="dom-interfaces">
1099 DOM Interfaces</h2>
1101 <p>
1102 CSS animation is exposed to the CSSOM through a pair of new interfaces describing the keyframes.
1105 <h3 id='CSSRule-interface'>
1106 Interface <code>CSSRule</code></h3>
1108 <p>
1109 The following 2 rule types are added to the <dfn>CSSRule</dfn> interface.
1110 They provide identification for the new keyframe and keyframes rules.
1113 <h4 id='CSSRule-IDL'>
1114 IDL Definition</h4>
1116 <pre class='idl'>
1117 interface CSSRule {
1118 ...
1119 const unsigned short KEYFRAMES_RULE = 7;
1120 const unsigned short KEYFRAME_RULE = 8;
1121 ...
1122 };</pre>
1125 <h3 id='CSSKeyframeRule-interface'>
1126 Interface <code>CSSKeyframeRule</code></3h>
1127 <p>
1128 The <dfn>CSSKeyframeRule</dfn> interface represents the style rule for a single key.
1131 <h4 id='CSSKeyframeRule-IDL'>
1132 IDL Definition</h4>
1134 <pre class='idl'>
1135 interface CSSKeyframeRule : CSSRule {
1136 attribute DOMString keyText;
1137 readonly attribute CSSStyleDeclaration style;
1138 };</pre>
1141 <h4 id='CSSKeyframeRule-attributes'>
1142 Attributes</h4>
1144 <dl>
1145 <dt><code><dfn id='CSSKeyframeRule-keyText'>keyText</dfn></code> of type <code>DOMString</code>
1146 <dd>
1147 This attribute represents the key
1148 as the string representation of a floating point number between 0 and 1.
1149 If the value in the CSS style is ''from''
1150 this value will be 0,
1151 and if the value in the CSS style is ''to''
1152 this value will be 1.
1154 <dt><code><dfn id='CSSKeyframeRule-style'>style</dfn></code> of type <code>CSSStyleDeclaration</code>
1155 <dd>
1156 This attribute represents the style associated with this keyframe.
1157 </dl>
1160 <h3 id='CSSKeyframesRule-interface'>
1161 Interface <code>CSSKeyframesRule</code></h3>
1163 <p>
1164 The <dfn>CSSKeyframesRule</dfn> interface represents a complete set of keyframes for a single animation.
1167 <h4 id='CSSKeyframesRule-IDL'>
1168 IDL Definition</h4>
1170 <pre class='idl'>
1171 interface CSSKeyframesRule : CSSRule {
1172 attribute DOMString name;
1173 readonly attribute CSSRuleList cssRules;
1175 void appendRule(in DOMString rule);
1176 void deleteRule(in DOMString key);
1177 CSSKeyframeRule findRule(in DOMString key);
1178 };</pre>
1181 <h4 id='CSSKeyframesRule-attributes'>
1182 Attributes</h4>
1184 <dl>
1185 <dt><code><dfn id='CSSKeyframesRule-name'>name</dfn></code> of type <code>DOMString</code>
1186 <dd>
1187 This attribute is the name of the keyframes, used by the 'animation-name' property.<br>
1189 <dt><code><dfn id='CSSKeyframesRules-cssRules'>cssRules</dfn></code> of type <code>CSSRuleList</code>
1190 <dd>
1191 This attribute gives access to the keyframes in the list.
1194 <h4 id='CSSKeyframesRule-appendRule'>
1195 The <code>appendRule</code> method</h4>
1197 <p>
1198 The <dfn>appendRule</dfn> method appends the passed CSSKeyframeRule into the list at the passed key.
1200 <p>
1201 Parameters:
1203 <dl>
1204 <dt><code>rule</code> of type <code>DOMString</code>
1206 <dd>
1207 The rule to be appended,
1208 expressed in the same syntax as one entry in the ''@keyframes'' rule.
1209 </dl>
1211 <p>
1212 No Return Value
1214 <p>
1215 No Exceptions
1218 <h4 id='CSSKeyframesRules-deleteRule'>
1219 The <code>deleteRule</code> method</h4>
1221 <p>
1222 The <dfn>deleteRule</dfn> method deletes the CSSKeyframeRule with the passed key.
1223 If a rule with this key does not exist,
1224 the method does nothing.
1226 <p>
1227 Parameters:
1229 <dl>
1230 <dt><code>key</code> of type <code>DOMString</code>
1231 <dd>
1232 The key which describes the rule to be deleted.
1233 The key must resolve to a number between 0 and 1,
1234 or the rule is ignored.
1235 </dl>
1237 <p>
1238 No Return Value
1240 <p>
1241 No Exceptions
1244 <h4 id='CSSKeyframesRule-findRule'>
1245 The <code>findRule</code> method</h4>
1247 <p>
1248 The <code>findRule</code> method returns the rule with a key matching the passed key.
1249 If no such rule exists,
1250 a null value is returned.
1252 <p>
1253 Parameters:
1255 <dl>
1256 <dt><code>key</code> of type <code>DOMString</code>
1257 <dd>
1258 The key which described the rule to find.
1259 The key must resolve to a number between 0 and 1,
1260 or the rule is ignored.
1261 </dl>
1263 <p>
1264 Return Value:
1266 <dl>
1267 <dt><code>CSSKeyframeRule</code>
1268 <dd>
1269 The found rule.
1270 </dl>
1272 <p>
1273 No Exceptions
1276 <h2 id="acknowledgments">Acknowledgments</h2>
1278 <p>Thanks especially to the feedback from
1279 Tab Atkins,
1280 Estelle Weyl,
1281 and all the rest of the
1282 <a href="http://lists.w3.org/Archives/Public/www-style/">www-style</a> community.
1284 <h2>References</h2>
1286 <h3 class="no-num">Normative references</h3>
1287 <!--normative-->
1289 <h3 class="no-num">Other references</h3>
1290 <!--informative-->
1294 <h2 class="no-num">Property index</h2>
1295 <!-- properties -->
1299 <h2 class="no-num" id="index">Index</h2>
1300 <!--index-->
1302 </body>
1303 </html>
1304 <!-- Keep this comment at the end of the file
1305 Local variables:
1306 mode: sgml
1307 sgml-declaration:"~/SGML/HTML4.decl"
1308 sgml-default-doctype-name:"html"
1309 sgml-minimize-attributes:t
1310 sgml-nofill-elements:("pre" "style" "br")
1311 sgml-live-element-indicator:t
1312 sgml-omittag:nil
1313 sgml-shorttag:nil
1314 sgml-namecase-general:t
1315 sgml-general-insert-case:lower
1316 sgml-always-quote-attributes:t
1317 sgml-indent-step:nil
1318 sgml-indent-data:t
1319 sgml-parent-document:nil
1320 sgml-exposed-tags:nil
1321 sgml-local-catalogs:nil
1322 sgml-local-ecat-files:nil
1323 End:
1324 -->