Tue, 19 Jun 2012 19:06:27 -0700
Fix typo in section 3 (missing 'a')
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 the property values defined in its 0% or 'from' keyframe
831 as soon as the animation is applied,
832 during the period defined by 'animation-delay'.
834 <p>
835 If the value for 'animation-fill-mode' is ''forwards'',
836 then the animation will apply the property values defined in its last executing keyframe
837 after the final iteration of the animation,
838 until the animation style is removed.
839 The last executing keyframe is the 'to' or '100%' keyframe,
840 unless the animation has 'animation-direction' set to ''alternate''
841 and both a finite and even iteration count,
842 in which case it is the 'from' or '0%' keyframe.
844 <p>
845 If the value for 'animation-fill-mode' is ''both'',
846 then the animation will follow the rules for both 'forwards' and 'backwards'.
847 That is, it will extend the animation properties in both directions.
849 <table class=propdef>
850 <tr>
851 <th>Name:</th>
852 <td><dfn>animation-fill-mode</dfn>
853 <tr>
854 <th><a href="#values">Value</a>:
855 <td>[ none | forwards | backwards | both ]#
856 <tr>
857 <th>Initial:
858 <td>''none''
859 <tr>
860 <th>Applies To:
861 <td>all elements
862 <tr>
863 <th>Inherited:
864 <td>no
865 <tr>
866 <th>Computed Value:
867 <td>as specified
868 <tr>
869 <th>Media:
870 <td>visual
871 <tr>
872 <th>Animatable:
873 <td>no
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-shorthand-property">
881 The 'animation' Shorthand Property
883 <p>
884 The 'animation' shorthand property combines seven of the animation properties into a single property.
886 <p>
887 Note that order is important in this property.
888 The first value that can be parsed as a <var><time></var> is assigned to the 'animation-duration'.
889 The second value that can be parsed as a <var><time></var> is assigned to 'animation-delay'.
891 <p class="issue">
892 An alternative proposal is to accept the font shorthand approach
893 of using a "/" character between the values of the same type.
894 e.g. 2s/4s would mean a duration of 2 seconds and a delay of 4 seconds.
896 <table class=propdef>
897 <tr>
898 <th>Name:</th>
899 <td><dfn>animation</dfn>
900 <tr>
901 <th><a href="#values">Value</a>:
902 <td>[ <'animation-name'> ||
903 <'animation-duration'> ||
904 <'animation-timing-function'> ||
905 <'animation-delay'> ||
906 <'animation-iteration-count'> ||
907 <'animation-direction'> ||
908 <'animation-fill-mode'> ]#
909 <tr>
910 <th>Initial:
911 <td>see individual properties
912 <tr>
913 <th>Applies To:
914 <td>all elements
915 <tr>
916 <th>Inherited:
917 <td>see individual properties
918 <tr>
919 <th>Computed Value:
920 <td>see individual properties
921 <tr>
922 <th>Media:
923 <td>visual
924 <tr>
925 <th>Animatable:
926 <td>no
927 <tr>
928 <th>Canonical Order:
929 <td><abbr title="follows order of property value definition">per grammar</abbr>
930 </table>
933 <h2 id="animation-events">
934 Animation Events</h2>
936 <p>
937 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>.
938 The start and end of an animation,
939 and the end of each iteration of an animation,
940 all generate DOM events.
941 An element can have multiple properties being animated simultaneously.
942 This can occur either with a single 'animation-name' value
943 with keyframes containing multiple properties,
944 or with multiple 'animation-name' values.
945 For the purposes of events,
946 each 'animation-name' specifies a single animation.
947 Therefore an event will be generated for each 'animation-name' value
948 and not necessarily for each property being animated.
950 <p>
951 The time the animation has been running is sent with each event generated.
952 This allows the event handler to determine the current iteration of a looping animation
953 or the current position of an alternating animation.
954 This time does not include any time the animation was in the ''paused'' play state.
957 <h3 id='AnimationEvent-interface'>
958 Interface <code>AnimationEvent</code>
960 <p>
961 The <dfn>AnimationEvent</dfn> interface provides specific contextual information associated with Animation events.
964 <h4 id='AnimationEvent-IDL'>
965 IDL Definition</h4>
967 <pre class='idl'>
968 interface AnimationEvent : Event {
969 readonly attribute DOMString animationName;
970 readonly attribute float elapsedTime;
971 void initAnimationEvent(in DOMString typeArg,
972 in boolean canBubbleArg,
973 in boolean cancelableArg,
974 in DOMString animationNameArg,
975 in float elapsedTimeArg);
976 };</pre>
979 <h4 id='AnimationEvent-attributes'>
980 Attributes</h4>
982 <dl>
983 <dt><code><dfn id='AnimationEvent-animationName'>animationName</dfn></code> of type <code>DOMString</code>, readonly
984 <dd>
985 The value of the 'animation-name' property of the animation that fired the event.
987 <dt><code><dfn id='AnimationEvent-elapsedTime'>elapsedTime</dfn></code> of type <code>float</code>, readonly
988 <dd>
989 The amount of time the animation has been running,
990 in seconds,
991 when this event fired,
992 excluding any time the animation was paused.
993 For an "animationstart" event,
994 the elapsedTime is zero unless there was a negative value for 'animation-delay',
995 in which case the event will be fired with an <code>elapsedTime</code> of (-1 * delay).
996 </dl>
999 <h4 id='AnimationEvent-initAnimationMethod'>
1000 The <code>initAnimationEvent</code> method</h4>
1002 <p>
1003 The <dfn>initAnimationEvent</dfn> method is used to initialize the value of an <code>AnimationEvent</code>
1004 created through the <a href='http://www.w3.org/TR/DOM-Level-2-Events/events.html#Events-DocumentEvent'><code>DocumentEvent</code></a> interface.
1005 This method may only be called before the <code>AnimationEvent</code> has been dispatched
1006 via the <code>dispatchEvent</code> method,
1007 though it may be called multiple times during that phase if necessary.
1008 If called multiple times,
1009 the final invocation takes precedence.
1011 <p>
1012 Parameters:
1014 <dl>
1015 <dt><code>typeArg</code> of type <code>DOMString</code>
1016 <dd>
1017 Specifies the event type.
1019 <dt><code>canBubbleArg</code> of type <code>boolean</code>
1020 <dd>
1021 Specifies whether or not the event can bubble.<br>
1023 <dt><code>cancelableArg</code> of type <code>boolean</code>
1024 <dd>
1025 Specifies whether or not the event's default action can be prevented.
1027 <dt><code>animationNameArg</code> of type <code>DOMString</code>
1028 <dd>
1029 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>
1031 <dt><code>elapsedTimeArg</code> of type <code>float</code>
1032 <dd>
1033 Specifies the amount of time,
1034 in seconds,
1035 the animation has been running at the time of initialization.
1036 </dl>
1038 <p>
1039 No Return Value
1041 <p>
1042 No Exceptions
1044 <h3 id='AnimationEvent-types'>
1045 Types of <code>AnimationEvent</code></h3>
1047 <p>
1048 The different types of Animation events that can occur are:
1050 <dl>
1051 <dt><dfn>animationstart</dfn>
1052 <dd>
1053 The <code>animationstart</code> event occurs at the start of the animation.
1054 If there is an 'animation-delay'
1055 then this event will fire once the delay period has expired.
1056 A negative delay will cause the event to fire with an <code>elapsedTime</code> equal to the absolute value of the delay.
1058 <ul>
1059 <li>Bubbles: Yes
1060 <li>Cancelable: No
1061 <li>Context Info: animationName
1062 </ul>
1064 <dt><dfn>animationend</dfn>
1065 <dd>
1066 The <code>animationend</code> event occurs when the animation finishes.
1068 <ul>
1069 <li>Bubbles: Yes
1070 <li>Cancelable: No
1071 <li>Context Info: animationName, elapsedTime
1072 </ul>
1074 <dt><dfn>animationiteration</dfn>
1075 <dd>
1076 The <code>animationiteration</code> event occurs at the end of each iteration of an animation,
1077 except when an <code>animationend</code> event would fire at the same time.
1078 This means that this event does not occur for animations with an iteration count of one or less.
1080 <ul>
1081 <li>Bubbles: Yes
1082 <li>Cancelable: No
1083 <li>Context Info: animationName, elapsedTime
1084 </ul>
1085 </dl>
1088 <h2 id="dom-interfaces">
1089 DOM Interfaces</h2>
1091 <p>
1092 CSS animation is exposed to the CSSOM through a pair of new interfaces describing the keyframes.
1095 <h3 id='CSSRule-interface'>
1096 Interface <code>CSSRule</code></h3>
1098 <p>
1099 The following 2 rule types are added to the <dfn>CSSRule</dfn> interface.
1100 They provide identification for the new keyframe and keyframes rules.
1103 <h4 id='CSSRule-IDL'>
1104 IDL Definition</h4>
1106 <pre class='idl'>
1107 interface CSSRule {
1108 ...
1109 const unsigned short KEYFRAMES_RULE = 7;
1110 const unsigned short KEYFRAME_RULE = 8;
1111 ...
1112 };</pre>
1115 <h3 id='CSSKeyframeRule-interface'>
1116 Interface <code>CSSKeyframeRule</code></3h>
1117 <p>
1118 The <dfn>CSSKeyframeRule</dfn> interface represents the style rule for a single key.
1121 <h4 id='CSSKeyframeRule-IDL'>
1122 IDL Definition</h4>
1124 <pre class='idl'>
1125 interface CSSKeyframeRule : CSSRule {
1126 attribute DOMString keyText;
1127 readonly attribute CSSStyleDeclaration style;
1128 };</pre>
1131 <h4 id='CSSKeyframeRule-attributes'>
1132 Attributes</h4>
1134 <dl>
1135 <dt><code><dfn id='CSSKeyframeRule-keyText'>keyText</dfn></code> of type <code>DOMString</code>
1136 <dd>
1137 This attribute represents the key
1138 as the string representation of a floating point number between 0 and 1.
1139 If the value in the CSS style is ''from''
1140 this value will be 0,
1141 and if the value in the CSS style is ''to''
1142 this value will be 1.
1144 <dt><code><dfn id='CSSKeyframeRule-style'>style</dfn></code> of type <code>CSSStyleDeclaration</code>
1145 <dd>
1146 This attribute represents the style associated with this keyframe.
1147 </dl>
1150 <h3 id='CSSKeyframesRule-interface'>
1151 Interface <code>CSSKeyframesRule</code></h3>
1153 <p>
1154 The <dfn>CSSKeyframesRule</dfn> interface represents a complete set of keyframes for a single animation.
1157 <h4 id='CSSKeyframesRule-IDL'>
1158 IDL Definition</h4>
1160 <pre class='idl'>
1161 interface CSSKeyframesRule : CSSRule {
1162 attribute DOMString name;
1163 readonly attribute CSSRuleList cssRules;
1165 void appendRule(in DOMString rule);
1166 void deleteRule(in DOMString key);
1167 CSSKeyframeRule findRule(in DOMString key);
1168 };</pre>
1171 <h4 id='CSSKeyframesRule-attributes'>
1172 Attributes</h4>
1174 <dl>
1175 <dt><code><dfn id='CSSKeyframesRule-name'>name</dfn></code> of type <code>DOMString</code>
1176 <dd>
1177 This attribute is the name of the keyframes, used by the 'animation-name' property.<br>
1179 <dt><code><dfn id='CSSKeyframesRules-cssRules'>cssRules</dfn></code> of type <code>CSSRuleList</code>
1180 <dd>
1181 This attribute gives access to the keyframes in the list.
1184 <h4 id='CSSKeyframesRule-appendRule'>
1185 The <code>appendRule</code> method</h4>
1187 <p>
1188 The <dfn>appendRule</dfn> method appends the passed CSSKeyframeRule into the list at the passed key.
1190 <p>
1191 Parameters:
1193 <dl>
1194 <dt><code>rule</code> of type <code>DOMString</code>
1196 <dd>
1197 The rule to be appended,
1198 expressed in the same syntax as one entry in the ''@keyframes'' rule.
1199 </dl>
1201 <p>
1202 No Return Value
1204 <p>
1205 No Exceptions
1208 <h4 id='CSSKeyframesRules-deleteRule'>
1209 The <code>deleteRule</code> method</h4>
1211 <p>
1212 The <dfn>deleteRule</dfn> method deletes the CSSKeyframeRule with the passed key.
1213 If a rule with this key does not exist,
1214 the method does nothing.
1216 <p>
1217 Parameters:
1219 <dl>
1220 <dt><code>key</code> of type <code>DOMString</code>
1221 <dd>
1222 The key which describes the rule to be deleted.
1223 The key must resolve to a number between 0 and 1,
1224 or the rule is ignored.
1225 </dl>
1227 <p>
1228 No Return Value
1230 <p>
1231 No Exceptions
1234 <h4 id='CSSKeyframesRule-findRule'>
1235 The <code>findRule</code> method</h4>
1237 <p>
1238 The <code>findRule</code> method returns the rule with a key matching the passed key.
1239 If no such rule exists,
1240 a null value is returned.
1242 <p>
1243 Parameters:
1245 <dl>
1246 <dt><code>key</code> of type <code>DOMString</code>
1247 <dd>
1248 The key which described the rule to find.
1249 The key must resolve to a number between 0 and 1,
1250 or the rule is ignored.
1251 </dl>
1253 <p>
1254 Return Value:
1256 <dl>
1257 <dt><code>CSSKeyframeRule</code>
1258 <dd>
1259 The found rule.
1260 </dl>
1262 <p>
1263 No Exceptions
1266 <h2 id="acknowledgments">Acknowledgments</h2>
1268 <p>Thanks especially to the feedback from
1269 Tab Atkins,
1270 Estelle Weyl,
1271 and all the rest of the
1272 <a href="http://lists.w3.org/Archives/Public/www-style/">www-style</a> community.
1274 <h2>References</h2>
1276 <h3 class="no-num">Normative references</h3>
1277 <!--normative-->
1279 <h3 class="no-num">Other references</h3>
1280 <!--informative-->
1284 <h2 class="no-num">Property index</h2>
1285 <!-- properties -->
1289 <h2 class="no-num" id="index">Index</h2>
1290 <!--index-->
1292 </body>
1293 </html>
1294 <!-- Keep this comment at the end of the file
1295 Local variables:
1296 mode: sgml
1297 sgml-declaration:"~/SGML/HTML4.decl"
1298 sgml-default-doctype-name:"html"
1299 sgml-minimize-attributes:t
1300 sgml-nofill-elements:("pre" "style" "br")
1301 sgml-live-element-indicator:t
1302 sgml-omittag:nil
1303 sgml-shorttag:nil
1304 sgml-namecase-general:t
1305 sgml-general-insert-case:lower
1306 sgml-always-quote-attributes:t
1307 sgml-indent-step:nil
1308 sgml-indent-data:t
1309 sgml-parent-document:nil
1310 sgml-exposed-tags:nil
1311 sgml-local-catalogs:nil
1312 sgml-local-ecat-files:nil
1313 End:
1314 -->