Thu, 12 Jul 2012 14:50:44 -0700
css3-animations ED: negative transition-duration values are invalid (bug 16806), handling of !important (bug 14792), fix property syntax defs, fix animation-delay referenced as 'foo' in prop index
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 block</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. In addition, keyframe rule declarations qualified with !important are ignored.
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 | IDENT ] [, [ none | 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> [, <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 When the duration is ''0s'' 'animation-fill-mode' still applies,
552 so an animation that fills backwards
553 will show the value of the 0% keyframe during any delay period,
554 and an animation that fills forwards will retain the value specified at the 100% keyframe,
555 even if the animation was instantaneous.
556 Also, animation events are still fired.
557 A negative 'animation-duration' value renders the declaration invalid.
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 [
575 ease | linear | ease-in | ease-out | ease-in-out |
576 step-start | step-end |
577 steps(<number> [, [ start | end ] ]?) |
578 cubic-bezier(<number>, <number>, <number>,
579 <number>)
580 ]
581 [,
582 [
583 ease | linear | ease-in | ease-out | ease-in-out |
584 step-start | step-end |
585 steps(<number> [, [ start | end ] ]?) |
586 cubic-bezier(<number>, <number>, <number>,
587 <number>)
588 ]
589 ]*
590 <tr>
591 <th>Initial:
592 <td>''ease''
593 <tr>
594 <th>Applies To:
595 <td>all elements
596 <tr>
597 <th>Inherited:
598 <td>no
599 <tr>
600 <th>Computed Value:
601 <td>as specified
602 <tr>
603 <th>Media:
604 <td>visual
605 <tr>
606 <th>Animatable:
607 <td>no
608 <tr>
609 <th>Canonical Order:
610 <td><abbr title="follows order of property value definition">per grammar</abbr>
611 </table>
613 <p>
614 For a keyframed animation,
615 the 'animation-timing-function' applies between keyframes,
616 not over the entire animation.
617 For example,
618 in the case of an ''ease-in-out'' timing function,
619 an animation will ease in at the start of the keyframe
620 and ease out at the end of the keyframe.
621 An 'animation-timing-function' defined within a keyframe block applies to that keyframe,
622 otherwise the timing function specified for the animation is used.
625 <h3 id="animation-iteration-count-property">
626 The 'animation-iteration-count' Property</h3>
628 <p>
629 The 'animation-iteration-count' property specifies the number of times an animation cycle is played.
630 The initial value is ''1'',
631 meaning the animation will play from beginning to end once.
632 A value of ''infinite'' will cause the animation to repeat forever.
633 Non-integer numbers will cause the animation to end part-way through a cycle.
634 Negative values of 'animation-iteration-count' are invalid.
635 This property is often used in conjunction an 'animation-direction' value of ''alternate'',
636 which will cause the animation to play in reverse on alternate cycles.
638 <table class=propdef>
639 <tr>
640 <th>Name:</th>
641 <td><dfn>animation-iteration-count</dfn>
642 <tr>
643 <th><a href="#values">Value</a>:
644 <td> [ infinite | <number> ]
645 [, [ infinite | <number> ] ]*
646 <tr>
647 <th>Initial:
648 <td>''1''
649 <tr>
650 <th>Applies To:
651 <td>all elements
652 <tr>
653 <th>Inherited:
654 <td>no
655 <tr>
656 <th>Computed Value:
657 <td>as specified
658 <tr>
659 <th>Media:
660 <td>visual
661 <tr>
662 <th>Animatable:
663 <td>no
664 <tr>
665 <th>Canonical Order:
666 <td><abbr title="follows order of property value definition">per grammar</abbr>
667 </table>
670 <h3 id="animation-direction-property">
671 The 'animation-direction' Property</h3>
673 <p>
674 The 'animation-direction' property defines whether or not the animation should play in reverse on some or all cycles.
675 When an animation is played in reverse the timing functions are also reversed.
676 For example, when played in reverse an ease-in animation would appear to be an ease-out animation.
678 <table class=propdef>
679 <tr>
680 <th>Name:</th>
681 <td><dfn>animation-direction</dfn>
682 <tr>
683 <th><a href="#values">Value</a>:
684 <td> [ normal | reverse | alternate | alternate-reverse ]
685 [, [ normal | reverse | alternate | alternate-reverse ] ]*
686 <tr>
687 <th>Initial:
688 <td>''normal''
689 <tr>
690 <th>Applies To:
691 <td>all elements
692 <tr>
693 <th>Inherited:
694 <td>no
695 <tr>
696 <th>Computed Value:
697 <td>as specified
698 <tr>
699 <th>Media:
700 <td>visual
701 <tr>
702 <th>Animatable:
703 <td>no
704 <tr>
705 <th>Canonical Order:
706 <td><abbr title="follows order of property value definition">per grammar</abbr>
707 </table>
709 <dl>
710 <dt><dfn>normal</dfn>
711 <dd>
712 All iterations of the animation are played as specified.
714 <dt><dfn>reverse</dfn>
715 <dd>
716 All iterations of the animation are played in the reverse direction from the way they were specified.
718 <dt><dfn>alternate</dfn>
719 <dd>
720 The animation cycle iterations that are odd counts are played in the normal direction,
721 and the animation cycle iterations that are even counts are played in a reverse direction.
723 <dt><dfn>alternate-reverse</dfn>
724 <dd>
725 The animation cycle iterations that are odd counts are played in the reverse direction,
726 and the animation cycle iterations that are even counts are played in a normal direction.
727 </dl>
729 <p class='note'>
730 Note that for the purpose of determining whether an iteration is even or odd,
731 iterations start counting from 1.
734 <h3 id="animation-play-state-property">
735 The 'animation-play-state' Property</h3>
737 <p>
738 The 'animation-play-state' property defines whether the animation is running or paused.
739 A running animation can be paused by setting this property to ''paused''.
740 To continue running a paused animation this property can be set to ''running''.
741 A paused animation will continue to display the current value of the animation in a static state,
742 as if the time of the animation is constant.
743 When a paused animation is resumed,
744 it restarts from the current value,
745 not necessarily from the beginning of the animation.
747 <table class=propdef>
748 <tr>
749 <th>Name:</th>
750 <td><dfn>animation-play-state</dfn>
751 <tr>
752 <th><a href="#values">Value</a>:
753 <td> [ running | paused ]
754 [, [ running | paused ] ]*
755 <tr>
756 <th>Initial:
757 <td>''running''
758 <tr>
759 <th>Applies To:
760 <td>all elements
761 <tr>
762 <th>Inherited:
763 <td>no
764 <tr>
765 <th>Computed Value:
766 <td>as specified
767 <tr>
768 <th>Media:
769 <td>visual
770 <tr>
771 <th>Animatable:
772 <td>no
773 <tr>
774 <th>Canonical Order:
775 <td><abbr title="follows order of property value definition">per grammar</abbr>
776 </table>
779 <h3 id="animation-delay-property">
780 The 'animation-delay' Property</h3>
782 <p>
783 The 'animation-delay' property defines when the animation will start.
784 It allows an animation to begin execution some time after it is applied.
785 An 'animation-delay' value of ''0s'' means the animation will execute as soon as it is applied.
786 Otherwise, the value specifies an offset from the moment the animation is applied,
787 and the animation will delay execution by that offset.
789 <p>
790 If the value for 'animation-delay' is a negative time offset
791 then the animation will execute the moment it is applied,
792 but will appear to have begun execution at the specified offset.
793 That is, the animation will appear to begin part-way through its play cycle.
794 In the case where an animation has implied starting values and a negative 'animation-delay',
795 the starting values are taken from the moment the animation is applied.
797 <table class=propdef>
798 <tr>
799 <th>Name:</th>
800 <td><dfn>animation-delay</dfn>
801 <tr>
802 <th><a href="#values">Value</a>:
803 <td> <time> [, <time>]*
804 <tr>
805 <th>Initial:
806 <td>''0s''
807 <tr>
808 <th>Applies To:
809 <td>all elements
810 <tr>
811 <th>Inherited:
812 <td>no
813 <tr>
814 <th>Computed Value:
815 <td>as specified
816 <tr>
817 <th>Media:
818 <td>visual
819 <tr>
820 <th>Animatable:
821 <td>no
822 <tr>
823 <th>Canonical Order:
824 <td><abbr title="follows order of property value definition">per grammar</abbr>
825 </table>
828 <h3 id="animation-fill-mode-property">
829 The 'animation-fill-mode' Property</h3>
831 <p>
832 The 'animation-fill-mode' property defines what values are applied by the animation outside the time it is executing.
833 By default, an animation will not affect property values
834 between the time it is applied
835 (the 'animation-name' property is set on an element)
836 and the time it begins execution
837 (which is determined by the 'animation-delay' property).
838 Also, by default an animation does not affect property values after the animation ends
839 (determined by the 'animation-duration' property).
840 The 'animation-fill-mode' property can override this behavior.
842 <p>
843 If the value for 'animation-fill-mode' is ''backwards'',
844 then the animation will apply
845 the property values defined in the keyframe
846 that will start the first iteration of the animation,
847 during the period defined by 'animation-delay'.
848 These are either the values of the ''from'' keyframe
849 (when 'animation-direction' is ''normal'' or ''alternate'')
850 or those of the ''to'' keyframe
851 (when 'animation-direction' is ''reverse'' or ''alternate-reverse'').
853 <p>
854 If the value for 'animation-fill-mode' is ''forwards'',
855 then after the animation ends
856 (as determined by its 'animation-iteration-count'),
857 the animation will apply
858 the property values for the time the animation ended.
859 When 'animation-iteration-count' is an integer greater than zero,
860 the values applied will be
861 those for the end of the last completed iteration of the animation
862 (rather than the values for
863 the start of the iteration that would be next).
864 When 'animation-iteration-count' is zero,
865 the values applied will be those that would start the first iteration
866 (just as when 'animation-fill-mode' is ''backwards'').
868 <p>
869 If the value for 'animation-fill-mode' is ''both'',
870 then the animation will follow the rules for both 'forwards' and 'backwards'.
871 That is, it will extend the animation properties in both directions.
873 <table class=propdef>
874 <tr>
875 <th>Name:</th>
876 <td><dfn>animation-fill-mode</dfn>
877 <tr>
878 <th><a href="#values">Value</a>:
879 <td> [ none | forwards | backwards | both ]
880 [, [ none | forwards | backwards | both ] ]*
881 <tr>
882 <th>Initial:
883 <td>''none''
884 <tr>
885 <th>Applies To:
886 <td>all elements
887 <tr>
888 <th>Inherited:
889 <td>no
890 <tr>
891 <th>Computed Value:
892 <td>as specified
893 <tr>
894 <th>Media:
895 <td>visual
896 <tr>
897 <th>Animatable:
898 <td>no
899 <tr>
900 <th>Canonical Order:
901 <td><abbr title="follows order of property value definition">per grammar</abbr>
902 </table>
905 <h3 id="animation-shorthand-property">
906 The 'animation' Shorthand Property
908 <p>
909 The 'animation' shorthand property combines seven of the animation properties into a single property.
911 <p>
912 Note that order is important in this property.
913 The first value that can be parsed as a <var><time></var> is assigned to the 'animation-duration'.
914 The second value that can be parsed as a <var><time></var> is assigned to 'animation-delay'.
916 <p class="issue">
917 An alternative proposal is to accept the font shorthand approach
918 of using a "/" character between the values of the same type.
919 e.g. 2s/4s would mean a duration of 2 seconds and a delay of 4 seconds.
921 <table class=propdef>
922 <tr>
923 <th>Name:</th>
924 <td><dfn>animation</dfn>
925 <tr>
926 <th><a href="#values">Value</a>:
927 <td>
928 [
929 <animation-name> || <animation-duration> ||
930 <animation-timing-function> || <animation-delay> ||
931 <animation-iteration-count> || <animation-direction> ||
932 <animation-fill-mode>
933 ]
934 [,
935 [
936 <animation-name> || <animation-duration> ||
937 <animation-timing-function> || <animation-delay> ||
938 <animation-iteration-count> || <animation-direction> ||
939 <animation-fill-mode>
940 ]
941 ]*
943 <tr>
944 <th>Initial:
945 <td>see individual properties
946 <tr>
947 <th>Applies To:
948 <td>all elements
949 <tr>
950 <th>Inherited:
951 <td>see individual properties
952 <tr>
953 <th>Computed Value:
954 <td>see individual properties
955 <tr>
956 <th>Media:
957 <td>visual
958 <tr>
959 <th>Animatable:
960 <td>no
961 <tr>
962 <th>Canonical Order:
963 <td><abbr title="follows order of property value definition">per grammar</abbr>
964 </table>
967 <h2 id="animation-events">
968 Animation Events</h2>
970 <p>
971 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>.
972 The start and end of an animation,
973 and the end of each iteration of an animation,
974 all generate DOM events.
975 An element can have multiple properties being animated simultaneously.
976 This can occur either with a single 'animation-name' value
977 with keyframes containing multiple properties,
978 or with multiple 'animation-name' values.
979 For the purposes of events,
980 each 'animation-name' specifies a single animation.
981 Therefore an event will be generated for each 'animation-name' value
982 and not necessarily for each property being animated.
984 <p>
985 The time the animation has been running is sent with each event generated.
986 This allows the event handler to determine the current iteration of a looping animation
987 or the current position of an alternating animation.
988 This time does not include any time the animation was in the ''paused'' play state.
991 <h3 id='AnimationEvent-interface'>
992 Interface <code>AnimationEvent</code>
994 <p>
995 The <dfn>AnimationEvent</dfn> interface provides specific contextual information associated with Animation events.
998 <h4 id='AnimationEvent-IDL'>
999 IDL Definition</h4>
1001 <pre class='idl'>
1002 interface AnimationEvent : Event {
1003 readonly attribute DOMString animationName;
1004 readonly attribute float elapsedTime;
1005 void initAnimationEvent(in DOMString typeArg,
1006 in boolean canBubbleArg,
1007 in boolean cancelableArg,
1008 in DOMString animationNameArg,
1009 in float elapsedTimeArg);
1010 };</pre>
1013 <h4 id='AnimationEvent-attributes'>
1014 Attributes</h4>
1016 <dl>
1017 <dt><code><dfn id='AnimationEvent-animationName'>animationName</dfn></code> of type <code>DOMString</code>, readonly
1018 <dd>
1019 The value of the 'animation-name' property of the animation that fired the event.
1021 <dt><code><dfn id='AnimationEvent-elapsedTime'>elapsedTime</dfn></code> of type <code>float</code>, readonly
1022 <dd>
1023 The amount of time the animation has been running,
1024 in seconds,
1025 when this event fired,
1026 excluding any time the animation was paused.
1027 For an "animationstart" event,
1028 the elapsedTime is zero unless there was a negative value for 'animation-delay',
1029 in which case the event will be fired with an <code>elapsedTime</code> of (-1 * delay).
1030 </dl>
1033 <h4 id='AnimationEvent-initAnimationMethod'>
1034 The <code>initAnimationEvent</code> method</h4>
1036 <p>
1037 The <dfn>initAnimationEvent</dfn> method is used to initialize the value of an <code>AnimationEvent</code>
1038 created through the <a href='http://www.w3.org/TR/DOM-Level-2-Events/events.html#Events-DocumentEvent'><code>DocumentEvent</code></a> interface.
1039 This method may only be called before the <code>AnimationEvent</code> has been dispatched
1040 via the <code>dispatchEvent</code> method,
1041 though it may be called multiple times during that phase if necessary.
1042 If called multiple times,
1043 the final invocation takes precedence.
1045 <p>
1046 Parameters:
1048 <dl>
1049 <dt><code>typeArg</code> of type <code>DOMString</code>
1050 <dd>
1051 Specifies the event type.
1053 <dt><code>canBubbleArg</code> of type <code>boolean</code>
1054 <dd>
1055 Specifies whether or not the event can bubble.<br>
1057 <dt><code>cancelableArg</code> of type <code>boolean</code>
1058 <dd>
1059 Specifies whether or not the event's default action can be prevented.
1061 <dt><code>animationNameArg</code> of type <code>DOMString</code>
1062 <dd>
1063 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>
1065 <dt><code>elapsedTimeArg</code> of type <code>float</code>
1066 <dd>
1067 Specifies the amount of time,
1068 in seconds,
1069 the animation has been running at the time of initialization.
1070 </dl>
1072 <p>
1073 No Return Value
1075 <p>
1076 No Exceptions
1078 <h3 id='AnimationEvent-types'>
1079 Types of <code>AnimationEvent</code></h3>
1081 <p>
1082 The different types of Animation events that can occur are:
1084 <dl>
1085 <dt><dfn>animationstart</dfn>
1086 <dd>
1087 The <code>animationstart</code> event occurs at the start of the animation.
1088 If there is an 'animation-delay'
1089 then this event will fire once the delay period has expired.
1090 A negative delay will cause the event to fire with an <code>elapsedTime</code> equal to the absolute value of the delay.
1092 <ul>
1093 <li>Bubbles: Yes
1094 <li>Cancelable: No
1095 <li>Context Info: animationName
1096 </ul>
1098 <dt><dfn>animationend</dfn>
1099 <dd>
1100 The <code>animationend</code> event occurs when the animation finishes.
1102 <ul>
1103 <li>Bubbles: Yes
1104 <li>Cancelable: No
1105 <li>Context Info: animationName, elapsedTime
1106 </ul>
1108 <dt><dfn>animationiteration</dfn>
1109 <dd>
1110 The <code>animationiteration</code> event occurs at the end of each iteration of an animation,
1111 except when an <code>animationend</code> event would fire at the same time.
1112 This means that this event does not occur for animations with an iteration count of one or less.
1114 <ul>
1115 <li>Bubbles: Yes
1116 <li>Cancelable: No
1117 <li>Context Info: animationName, elapsedTime
1118 </ul>
1119 </dl>
1122 <h2 id="dom-interfaces">
1123 DOM Interfaces</h2>
1125 <p>
1126 CSS animation is exposed to the CSSOM through a pair of new interfaces describing the keyframes.
1129 <h3 id='CSSRule-interface'>
1130 Interface <code>CSSRule</code></h3>
1132 <p>
1133 The following 2 rule types are added to the <dfn>CSSRule</dfn> interface.
1134 They provide identification for the new keyframe and keyframes rules.
1137 <h4 id='CSSRule-IDL'>
1138 IDL Definition</h4>
1140 <pre class='idl'>
1141 interface CSSRule {
1142 ...
1143 const unsigned short KEYFRAMES_RULE = 7;
1144 const unsigned short KEYFRAME_RULE = 8;
1145 ...
1146 };</pre>
1149 <h3 id='CSSKeyframeRule-interface'>
1150 Interface <code>CSSKeyframeRule</code></3h>
1151 <p>
1152 The <dfn>CSSKeyframeRule</dfn> interface represents the style rule for a single key.
1155 <h4 id='CSSKeyframeRule-IDL'>
1156 IDL Definition</h4>
1158 <pre class='idl'>
1159 interface CSSKeyframeRule : CSSRule {
1160 attribute DOMString keyText;
1161 readonly attribute CSSStyleDeclaration style;
1162 };</pre>
1165 <h4 id='CSSKeyframeRule-attributes'>
1166 Attributes</h4>
1168 <dl>
1169 <dt><code><dfn id='CSSKeyframeRule-keyText'>keyText</dfn></code> of type <code>DOMString</code>
1170 <dd>
1171 This attribute represents the key
1172 as the string representation of a floating point number between 0 and 1.
1173 If the value in the CSS style is ''from''
1174 this value will be 0,
1175 and if the value in the CSS style is ''to''
1176 this value will be 1.
1178 <dt><code><dfn id='CSSKeyframeRule-style'>style</dfn></code> of type <code>CSSStyleDeclaration</code>
1179 <dd>
1180 This attribute represents the style associated with this keyframe.
1181 </dl>
1184 <h3 id='CSSKeyframesRule-interface'>
1185 Interface <code>CSSKeyframesRule</code></h3>
1187 <p>
1188 The <dfn>CSSKeyframesRule</dfn> interface represents a complete set of keyframes for a single animation.
1191 <h4 id='CSSKeyframesRule-IDL'>
1192 IDL Definition</h4>
1194 <pre class='idl'>
1195 interface CSSKeyframesRule : CSSRule {
1196 attribute DOMString name;
1197 readonly attribute CSSRuleList cssRules;
1199 void appendRule(in DOMString rule);
1200 void deleteRule(in DOMString key);
1201 CSSKeyframeRule findRule(in DOMString key);
1202 };</pre>
1205 <h4 id='CSSKeyframesRule-attributes'>
1206 Attributes</h4>
1208 <dl>
1209 <dt><code><dfn id='CSSKeyframesRule-name'>name</dfn></code> of type <code>DOMString</code>
1210 <dd>
1211 This attribute is the name of the keyframes, used by the 'animation-name' property.<br>
1213 <dt><code><dfn id='CSSKeyframesRules-cssRules'>cssRules</dfn></code> of type <code>CSSRuleList</code>
1214 <dd>
1215 This attribute gives access to the keyframes in the list.
1218 <h4 id='CSSKeyframesRule-appendRule'>
1219 The <code>appendRule</code> method</h4>
1221 <p>
1222 The <dfn>appendRule</dfn> method appends the passed CSSKeyframeRule into the list at the passed key.
1224 <p>
1225 Parameters:
1227 <dl>
1228 <dt><code>rule</code> of type <code>DOMString</code>
1230 <dd>
1231 The rule to be appended,
1232 expressed in the same syntax as one entry in the ''@keyframes'' rule.
1233 </dl>
1235 <p>
1236 No Return Value
1238 <p>
1239 No Exceptions
1242 <h4 id='CSSKeyframesRules-deleteRule'>
1243 The <code>deleteRule</code> method</h4>
1245 <p>
1246 The <dfn>deleteRule</dfn> method deletes the CSSKeyframeRule with the passed key.
1247 If a rule with this key does not exist,
1248 the method does nothing.
1250 <p>
1251 Parameters:
1253 <dl>
1254 <dt><code>key</code> of type <code>DOMString</code>
1255 <dd>
1256 The key which describes the rule to be deleted.
1257 The key must resolve to a number between 0 and 1,
1258 or the rule is ignored.
1259 </dl>
1261 <p>
1262 No Return Value
1264 <p>
1265 No Exceptions
1268 <h4 id='CSSKeyframesRule-findRule'>
1269 The <code>findRule</code> method</h4>
1271 <p>
1272 The <code>findRule</code> method returns the rule with a key matching the passed key.
1273 If no such rule exists,
1274 a null value is returned.
1276 <p>
1277 Parameters:
1279 <dl>
1280 <dt><code>key</code> of type <code>DOMString</code>
1281 <dd>
1282 The key which described the rule to find.
1283 The key must resolve to a number between 0 and 1,
1284 or the rule is ignored.
1285 </dl>
1287 <p>
1288 Return Value:
1290 <dl>
1291 <dt><code>CSSKeyframeRule</code>
1292 <dd>
1293 The found rule.
1294 </dl>
1296 <p>
1297 No Exceptions
1300 <h2 id="acknowledgments">Acknowledgments</h2>
1302 <p>Thanks especially to the feedback from
1303 Tab Atkins,
1304 Estelle Weyl,
1305 and all the rest of the
1306 <a href="http://lists.w3.org/Archives/Public/www-style/">www-style</a> community.
1308 <h2>References</h2>
1310 <h3 class="no-num">Normative references</h3>
1311 <!--normative-->
1313 <h3 class="no-num">Other references</h3>
1314 <!--informative-->
1318 <h2 class="no-num">Property index</h2>
1319 <!-- properties -->
1323 <h2 class="no-num" id="index">Index</h2>
1324 <!--index-->
1326 </body>
1327 </html>
1328 <!-- Keep this comment at the end of the file
1329 Local variables:
1330 mode: sgml
1331 sgml-declaration:"~/SGML/HTML4.decl"
1332 sgml-default-doctype-name:"html"
1333 sgml-minimize-attributes:t
1334 sgml-nofill-elements:("pre" "style" "br")
1335 sgml-live-element-indicator:t
1336 sgml-omittag:nil
1337 sgml-shorttag:nil
1338 sgml-namecase-general:t
1339 sgml-general-insert-case:lower
1340 sgml-always-quote-attributes:t
1341 sgml-indent-step:nil
1342 sgml-indent-data:t
1343 sgml-parent-document:nil
1344 sgml-exposed-tags:nil
1345 sgml-local-catalogs:nil
1346 sgml-local-ecat-files:nil
1347 End:
1348 -->