css3-animations/Overview.src.html@f4ccc8c2ecf0
css3-animations/Overview.src.html
Thu, 20 Sep 2012 12:31:33 -0700
- author
- L. David Baron <dbaron@dbaron.org>
- date
- Thu, 20 Sep 2012 12:31:33 -0700
- changeset 6739
- f4ccc8c2ecf0
- parent 6737
- ef8f9efb1230
- child 6806
- fddad400b1ff
- permissions
- -rw-r--r--
[css3-transitions][css3-animations] Make single-* productions introduced earlier today have hyperlinks and better ids.
1 <!DOCTYPE html>
2 <html lang="en">
3 <head>
4 <title>CSS Animations</title>
5 <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
6 <link rel="stylesheet" type="text/css" href="../default.css">
7 <link rel="stylesheet" type="text/css" href="http://www.w3.org/StyleSheets/TR/W3C-ED.css">
8 <style type="text/css">
9 div.prod { margin: 1em 2em; }
10 </style>
11 </head>
13 <body>
15 <div class="head">
16 <!--logo-->
18 <h1>CSS Animations</h1>
20 <h2 class="no-num no-toc">[LONGSTATUS] [DATE]</h2>
21 <dl>
22 <dt>This version:
23 <dd><a href="[VERSION]">http://dev.w3.org/csswg/css3-animations/</a>
24 <!--http://www.w3.org/TR/[YEAR]/WD-[SHORTNAME]-[CDATE]/-->
25 <dt>Latest version:
26 <dd><a
27 href="http://www.w3.org/TR/css3-animations/">[LATEST]</a>
28 <dt>Editor's draft:
29 <dd><a href="http://dev.w3.org/csswg/[SHORTNAME]/">http://dev.w3.org/csswg/[SHORTNAME]/</a>
31 <dt>Previous version:
32 <dd><a href="http://www.w3.org/TR/2012/WD-css3-animations-20120403/">
33 http://www.w3.org/TR/2012/WD-css3-animations-20120403/</a>
34 <dt id="editors-list">Editors:
35 <dd><a href="mailto:dino@apple.com">Dean Jackson</a> (<a
36 href="http://www.apple.com/">Apple Inc</a>)
37 <dd><a href="mailto:hyatt@apple.com">David Hyatt</a> (<a
38 href="http://www.apple.com/">Apple Inc</a>)
39 <dd><a href="mailto:cmarrin@apple.com">Chris Marrin</a> (<a
40 href="http://www.apple.com/">Apple Inc</a>)
41 <dd><a href="mailto:sylvaing@microsoft.com">Sylvain Galineau</a>
42 (<a class=org href="http://www.microsoft.com/">Microsoft</a>)
43 <dd class=vcard><a class=fn href="http://dbaron.org/">L. David Baron</a>
44 (<a class=org href="http://www.mozilla.org/">Mozilla</a>)
46 <dt>Issues list:
47 <dd><a href="https://www.w3.org/Bugs/Public/buglist.cgi?query_format=advanced&product=CSS&component=Animations&resolution=---&cmdtype=doit">in Bugzilla</a>
49 <dt>Discussion:
50 <dd><a href="http://lists.w3.org/Archives/Public/www-style/">www-style@w3.org</a> with subject line “<kbd>[[SHORTNAME]] <var>… message topic …</var></kbd>”
52 <dt>Test suite:
53 <dd>none yet
54 </dl>
56 <!--copyright-->
58 <hr title="Separator for header">
59 </div>
61 <h2 class="no-num no-toc" id="abstract">
62 Abstract</h2>
64 <p>
65 This CSS module describes a way for authors to animate the values of CSS properties over time,
66 using keyframes.
67 The behavior of these keyframe animations can be controlled by specifying their duration,
68 number of repeats,
69 and repeating behavior.
72 <h2 class="no-num no-toc" id="status">
73 Status of this document</h2>
74 <!--status-->
77 <h2 class="no-num no-toc" id="contents">
78 Table of contents</h2>
79 <!--toc-->
82 <h2 id="introduction">
83 Introduction</h2>
85 <p><em>This section is not normative.</em>
87 <p>
88 CSS Transitions [[CSS3-TRANSITIONS]]
89 provide a way to interpolate CSS property values
90 when they change as a result of underlying property changes.
91 This provides an easy way to do simple animation,
92 but the start and end states of the animation are controlled by the existing property values,
93 and transitions provide little control to the author on how the animation progresses.
95 <p>
96 This proposal introduces <dfn>defined animations</dfn>,
97 in which the author can specify the changes in CSS properties over time as a set of keyframes.
98 Animations are similar to transitions
99 in that they change the presentational value of CSS properties over time.
100 The principal difference is that
101 while transitions trigger <em>implicitly</em> when property values change,
102 animations are <em>explicitly</em> executed when the animation properties are applied.
103 Because of this,
104 animations require explicit values for the properties being animated.
105 These values are specified using animation keyframes, described below.
107 <p>
108 Many aspects of the animation can be controlled,
109 including how many times the animation iterates,
110 whether or not it alternates between the begin and end values,
111 and whether or not the animation should be running or paused.
112 An animation can also delay its start time.
115 <h2 id="animations">
116 Animations</h2>
118 <p>
119 CSS Animations affect computed property values.
120 During the execution of an animation,
121 the computed value for a property is controlled by the animation.
122 This overrides the value specified in the normal styling system.
125 <p>
126 If at one point in time there are multiple animations specifying behavior for the same property,
127 the animation whose name occurs last in the value of 'animation-name'
128 will override the other animations at that point.
131 <p>
132 An animation does not affect the computed value before the application of the animation,
133 before the animation delay has expired,
134 and after the end of the animation.
137 <div class="figure">
138 <img src="sandwich.png" alt="">
140 <p class="caption">
141 Computation of animated property values
142 </div>
144 <p>
145 The diagram above shows how property values are computed.
146 The intrinsic style is shown at the top of the diagram.
147 The computed value is derived from intrinsic style
148 at the times when an animation is not running
149 and also when an animation is delayed
150 (see below for specification of animation delay).
151 During an animation,
152 the computed style is derived from the animated value.
155 <p>
156 The start time of an animation is the latter of two moments:
157 the time at which the style is resolved that specifies the animation,
158 or the time the document's load event is fired.
159 Therefore, an animation specified in the document style sheet
160 will begin at the document load.
161 An animation specified on an element by modifying the style after the document has loaded
162 will start when the style is resolved.
163 That may be immediately in the case of a pseudo style rule such as hover,
164 or may be when the scripting engine returns control to the browser
165 (in the case of style applied by script).
168 <p>
169 An animation applies to an element
170 if the element has a value for 'animation-name' that references a valid keyframes rule.
171 Once an animation has started
172 it continues until it ends
173 or the 'animation-name' is removed.
174 The values used for the keyframes and animation properties are snapshotted at the time the animation starts.
175 Changing them during the execution of the animation has no effect.
176 Note also that changing the value of 'animation-name' does not necessarily restart an animation
177 (e.g., if a list of animations are applied and one is removed from the list,
178 only that animation will stop;
179 The other animations will continue).
180 In order to restart an animation,
181 it must be removed then reapplied.
184 <p>
185 The end of the animation is defined by the combination of the
186 'animation-duration',
187 'animation-iteration-count' and
188 'animation-fill-mode' properties.
191 <div class="example">
192 <pre>
193 div {
194 animation-name: diagonal-slide;
195 animation-duration: 5s;
196 animation-iteration-count: 10;
197 }
199 @keyframes diagonal-slide {
201 from {
202 left: 0;
203 top: 0;
204 }
206 to {
207 left: 100px;
208 top: 100px;
209 }
211 }</pre>
213 <p>
214 This will produce an animation
215 that moves an element from (0, 0) to (100px, 100px)
216 over five seconds
217 and repeats itself nine times
218 (for a total of ten iterations).
219 </div>
221 <h2 id="keyframes">
222 Keyframes</h2>
223 <p>
224 Keyframes are used to specify the values for the animating properties
225 at various points during the animation.
226 The keyframes specify the behavior of one cycle of the animation;
227 the animation may iterate one or more times.
229 <p>
230 Keyframes are specified using a specialized CSS at-rule.
231 A @keyframes rule consists of the keyword "@keyframes",
232 followed by an identifier giving a name for the animation
233 (which will be referenced using 'animation-name'),
234 followed by a set of style rules
235 (delimited by curly braces).
237 <p>
238 The <dfn>keyframe selector</dfn> for a keyframe style rule
239 consists of a comma-separated list of percentage values
240 or the keywords 'from' or 'to'.
241 The selector is used to specify the percentage along the duration of the animation that the keyframe represents.
242 The keyframe itself is specified by the block of property values declared on the selector.
243 The keyword 'from' is equivalent to the value ''0%''.
244 The keyword 'to' is equivalent to the value ''100%''.
245 <span class='note'>Note that the percentage unit specifier must be used on percentage values.
246 Therefore, ''0'' is an invalid keyframe selector.</span>
248 <p>
249 If a ''0%'' or ''from'' keyframe is not specified,
250 then the user agent constructs a ''0%'' keyframe
251 using the computed values of the properties being animated.
252 If a ''100%'' or ''to'' keyframe is not specified,
253 then the user agent constructs a ''100%'' keyframe
254 using the computed values of the properties being animated.
255 If a keyframe selector specifies
256 negative percentage values or
257 values higher than 100%,
258 then the keyframe will be ignored.
260 <p>
261 The <dfn>keyframe declaration block</dfn> for a keyframe rule
262 consists of properties and values.
263 Properties that are unable to be animated are ignored in these rules,
264 with the exception of 'animation-timing-function',
265 the behavior of which is described below. In addition, keyframe rule declarations qualified with !important are ignored.
267 <p class="issue">
268 Need to describe what happens if a property is not present in all keyframes.
270 <p>
271 The @keyframes rule that is used by an animation
272 will be the last one encountered in sorted rules order
273 that matches the name of the animation specified by the 'animation-name' property.
274 @keyframes rules do not cascade;
275 therefore, an animation will never derive keyframes from more than one @keyframes rule.
277 <p>
278 To determine the set of keyframes,
279 all of the values in the selectors are sorted in increasing order by time.
280 If there are any duplicates,
281 then the last keyframe specified inside the @keyframes rule
282 will be used to provide the keyframe information for that time.
283 There is no cascading within a @keyframes rule if multiple keyframes specify the same keyframe selector values.
285 <p>
286 If a property is not specified for a keyframe,
287 or is specified but invalid,
288 the animation of that property proceeds as if that keyframe did not exist.
289 Conceptually,
290 it is as if a set of keyframes is constructed for each property that is present in any of the keyframes,
291 and an animation is run independently for each property.
293 <div class="example">
294 <pre>
295 @keyframes wobble {
296 0% {
297 left: 100px;
298 }
300 40% {
301 left: 150px;
302 }
304 60% {
305 left: 75px;
306 }
308 100% {
309 left: 100px;
310 }
311 }</pre>
313 <p>
314 Four keyframes are specified for the animation named "wobble".
315 In the first keyframe,
316 shown at the beginning of the animation cycle,
317 the value of the 'left' property being animated is ''100px''.
318 By 40% of the animation duration,
319 'left' has animated to ''150px''.
320 At 60% of the animation duration,
321 'left' has animated back to ''75px''.
322 At the end of the animation cycle,
323 the value of 'left' has returned to ''100px''.
324 The diagram below shows the state of the animation if it were given a duration of ''10s''.
326 <div class="figure">
327 <img src="animation1.png" alt="">
329 <p class="caption">
330 Animations states specified by keyframes
331 </div>
332 </div>
334 <p>
335 The following is the grammar for the keyframes rule.
337 <pre>
338 keyframes_rule: KEYFRAMES_SYM S+ IDENT S* '{' S* keyframes_blocks '}' S*;
340 keyframes_blocks: [ keyframe_selector '{' S* declaration? [ ';' S* declaration? ]* '}' S* ]* ;
342 keyframe_selector: [ FROM_SYM | TO_SYM | PERCENTAGE ] S* [ ',' S* [ FROM_SYM | TO_SYM | PERCENTAGE ] S* ]*;
344 @{K}{E}{Y}{F}{R}{A}{M}{E}{S} {return KEYFRAMES_SYM;}
345 {F}{R}{O}{M} {return FROM_SYM;}
346 {T}{O} {return TO_SYM;}</pre>
349 <h3 id="timing-functions">
350 Timing functions for keyframes</h3>
352 <p>
353 A keyframe style rule may also declare the timing function that is to be used
354 as the animation moves to the next keyframe.
356 <div class="example">
357 <pre>
358 @keyframes bounce {
360 from {
361 top: 100px;
362 animation-timing-function: ease-out;
363 }
365 25% {
366 top: 50px;
367 animation-timing-function: ease-in;
368 }
370 50% {
371 top: 100px;
372 animation-timing-function: ease-out;
373 }
375 75% {
376 top: 75px;
377 animation-timing-function: ease-in;
378 }
380 to {
381 top: 100px;
382 }
384 }</pre>
386 <p>
387 Five keyframes are specified for the animation named "bounce".
388 Between the first and second keyframe
389 (i.e., between 0% and 25%)
390 an ''ease-out'' timing function is used.
391 Between the second and third keyframe
392 (i.e., between 25% and 50%)
393 an ''ease-in'' timing function is used.
394 And so on.
395 The effect will appear as an element that moves up the page ''50px'',
396 slowing down as it reaches its highest point
397 then speeding up as it falls back to ''100px''.
398 The second half of the animation behaves in a similar manner,
399 but only moves the element ''25px'' up the page.
400 </div>
402 <p>
403 A timing function specified on the "to" or 100% keyframe is ignored.
405 <p>
406 See the 'animation-timing-function' property for more information.
409 <h3 id="animation-name-property">
410 The 'animation-name' Property</h3>
412 <p>
413 The 'animation-name' property defines a list of animations that apply.
414 Each name is used to select the keyframe at-rule
415 that provides the property values for the animation.
416 If the name does not match any keyframe at-rule,
417 there are no properties to be animated
418 and the animation will not execute.
419 Furthermore,
420 if the animation name is ''none''
421 then there will be no animation.
422 This can be used to override any animations coming from the cascade.
423 If multiple animations are attempting to modify the same property,
424 then the animation closest to the end of the list of names wins.
426 <p id="list-matching">
427 Each animation listed by name
428 should have a corresponding value for the other animation properties listed below.
429 If the lists of values for the other animation properties do not have the same length,
430 the length of the 'animation-name' list
431 determines the number of items in each list examined when starting animations.
432 The lists are matched up from the first value:
433 excess values at the end are not used.
434 If one of the other properties doesn't have enough comma-separated values to match the number of values of 'animation-name',
435 the UA must calculate its used value by repeating the list of values until there are enough.
436 This truncation or repetition does not affect the computed value.
437 <span class="note">Note: This is analogous to the behavior of the 'background-*'properties,
438 with 'background-image' analogous to 'animation-name'.</span>
441 <table class=propdef>
442 <tr>
443 <th>Name:</th>
444 <td><dfn>animation-name</dfn>
445 <tr>
446 <th><a href="#values">Value</a>:
447 <td><span><single-animation-name></span> [ ',' <span><single-animation-name></span> ]*
448 <tr>
449 <th>Initial:
450 <td>''none''
451 <tr>
452 <th>Applies To:
453 <td>all elements
454 <tr>
455 <th>Inherited:
456 <td>no
457 <tr>
458 <th>Animatable:
459 <td>no
460 <tr>
461 <th>Percentages:
462 <td>N/A
463 <tr>
464 <th>Media:
465 <td>visual
466 <tr>
467 <th>Computed Value:
468 <td>As specified
469 <tr>
470 <th>Canonical Order:
471 <td><abbr title="follows order of property value definition">per grammar</abbr>
472 </table>
474 <div class="prod">
475 <dfn id="single-animation-name"><single-animation-name></dfn> = none | <IDENT>
476 </div>
478 <!--
479 <p>
480 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.
482 <div class="example">
483 <p style="display:none">
484 Example(s):
486 <pre>
487 @keyframes 'border-bloat' {
488 from {
489 border-width: 0;
490 }
491 to {
492 border-width: 10px;
493 }
494 }
496 @keyframes 'border-diet' {
497 from {
498 border-width: 4px;
499 }
500 to {
501 border-width: 2px;
502 }
503 }
505 div {
506 animation-name: 'border-bloat', 'border-diet';
507 animation-duration: 10s, 4s;
508 }
509 </pre>
510 <p>
511 The above example has two animations executing on the same property, 'border-width'. The animations are additive. That is, the
512 resulting value for the property will be the addition of the values from the
513 two animations.
515 <p>
516 At time '0s' the element's border will be 4px wide (0px from 'border-bloat' plus 4px from 'border-diet').
517 At time '4s' the element's border will be 6px wide (4px from 'border-bloat' plus 2px from 'border-diet').
518 At time '10s' the element's border will be 10px wide (10px from 'border-bloat' and no addition from
519 'border-diet' as it is no longer executing).
521 </div>
522 -->
525 <h3 id="animation-duration-property">
526 The 'animation-duration' Property</h3>
528 <p>
529 The 'animation-duration' property defines the length of time that an animation takes to complete one cycle.
532 <table class=propdef>
533 <tr>
534 <th>Name:</th>
535 <td><dfn>animation-duration</dfn>
536 <tr>
537 <th><a href="#values">Value</a>:
538 <td> <span><time></span> [, <span><time></span>]*
539 <tr>
540 <th>Initial:
541 <td>''0s''
542 <tr>
543 <th>Applies To:
544 <td>all elements
545 <tr>
546 <th>Inherited:
547 <td>no
548 <tr>
549 <th>Animatable:
550 <td>no
551 <tr>
552 <th>Percentages:
553 <td>N/A
554 <tr>
555 <th>Media:
556 <td>visual
557 <tr>
558 <th>Computed Value:
559 <td>as specified
560 <tr>
561 <th>Canonical Order:
562 <td><abbr title="follows order of property value definition">per grammar</abbr>
563 </table>
565 <p>
566 The initial value is ''0s'',
567 meaning that the animation takes no time.
568 When the duration is ''0s'' 'animation-fill-mode' still applies,
569 so an animation that fills backwards
570 will show the value of the 0% keyframe during any delay period,
571 and an animation that fills forwards will retain the value specified at the 100% keyframe,
572 even if the animation was instantaneous.
573 Also, animation events are still fired.
574 A negative 'animation-duration' value renders the declaration invalid.
577 <h3 id="animation-timing-function-property">
578 The 'animation-timing-function' Property</h3>
580 <p>
581 The 'animation-timing-function' property describes how the animation will progress over one cycle of its duration.
582 See the 'transition-timing-function' property [[!CSS3-TRANSITIONS]] for a complete description of timing function calculation.
584 <table class=propdef>
585 <tr>
586 <th>Name:</th>
587 <td><dfn>animation-timing-function</dfn>
588 <tr>
589 <th><a href="#values">Value</a>:
590 <td><span><single-animation-timing-function></span> [ ',' <span><single-animation-timing-function></span> ]*
591 <tr>
592 <th>Initial:
593 <td>''ease''
594 <tr>
595 <th>Applies To:
596 <td>all elements
597 <tr>
598 <th>Inherited:
599 <td>no
600 <tr>
601 <th>Animatable:
602 <td>no
603 <tr>
604 <th>Percentages:
605 <td>N/A
606 <tr>
607 <th>Media:
608 <td>visual
609 <tr>
610 <th>Computed Value:
611 <td>as specified
612 <tr>
613 <th>Canonical Order:
614 <td><abbr title="follows order of property value definition">per grammar</abbr>
615 </table>
617 <div class="prod">
618 <dfn id="single-animation-timing-function"><single-animation-timing-function></dfn> =
619 ease | linear | ease-in | ease-out | ease-in-out |
620 step-start | step-end |
621 steps(<number> [, [ start | end ] ]?) |
622 cubic-bezier(<number>, <number>, <number>,
623 <number>)
624 </div>
626 <p>
627 For a keyframed animation,
628 the 'animation-timing-function' applies between keyframes,
629 not over the entire animation.
630 For example,
631 in the case of an ''ease-in-out'' timing function,
632 an animation will ease in at the start of the keyframe
633 and ease out at the end of the keyframe.
634 An 'animation-timing-function' defined within a keyframe block applies to that keyframe,
635 otherwise the timing function specified for the animation is used.
638 <h3 id="animation-iteration-count-property">
639 The 'animation-iteration-count' Property</h3>
641 <p>
642 The 'animation-iteration-count' property specifies the number of times an animation cycle is played.
643 The initial value is ''1'',
644 meaning the animation will play from beginning to end once.
645 A value of ''infinite'' will cause the animation to repeat forever.
646 Non-integer numbers will cause the animation to end part-way through a cycle.
647 Negative values of 'animation-iteration-count' are invalid.
648 This property is often used in conjunction an 'animation-direction' value of ''alternate'',
649 which will cause the animation to play in reverse on alternate cycles.
651 <table class=propdef>
652 <tr>
653 <th>Name:</th>
654 <td><dfn>animation-iteration-count</dfn>
655 <tr>
656 <th><a href="#values">Value</a>:
657 <td><span><single-animation-iteration-count></span> [ ',' <span><single-animation-iteration-count></span> ]*
658 <tr>
659 <th>Initial:
660 <td>''1''
661 <tr>
662 <th>Applies To:
663 <td>all elements
664 <tr>
665 <th>Inherited:
666 <td>no
667 <tr>
668 <th>Animatable:
669 <td>no
670 <tr>
671 <th>Percentages:
672 <td>N/A
673 <tr>
674 <th>Media:
675 <td>visual
676 <tr>
677 <th>Computed Value:
678 <td>as specified
679 <tr>
680 <th>Canonical Order:
681 <td><abbr title="follows order of property value definition">per grammar</abbr>
682 </table>
684 <div class="prod">
685 <dfn id="single-animation-iteration-count"><single-animation-iteration-count></dfn> =
686 infinite | <number>
687 </div>
689 <h3 id="animation-direction-property">
690 The 'animation-direction' Property</h3>
692 <p>
693 The 'animation-direction' property defines whether or not the animation should play in reverse on some or all cycles.
694 When an animation is played in reverse the timing functions are also reversed.
695 For example, when played in reverse an ease-in animation would appear to be an ease-out animation.
697 <table class=propdef>
698 <tr>
699 <th>Name:</th>
700 <td><dfn>animation-direction</dfn>
701 <tr>
702 <th><a href="#values">Value</a>:
703 <td><span><single-animation-direction></span> [ ',' <span><single-animation-direction></span> ]*
704 <tr>
705 <th>Initial:
706 <td>''normal''
707 <tr>
708 <th>Applies To:
709 <td>all elements
710 <tr>
711 <th>Inherited:
712 <td>no
713 <tr>
714 <th>Animatable:
715 <td>no
716 <tr>
717 <th>Percentages:
718 <td>N/A
719 <tr>
720 <th>Media:
721 <td>visual
722 <tr>
723 <th>Computed Value:
724 <td>as specified
725 <tr>
726 <th>Canonical Order:
727 <td><abbr title="follows order of property value definition">per grammar</abbr>
728 </table>
730 <div class="prod">
731 <dfn id="single-animation-direction"><single-animation-direction></dfn> =
732 normal | reverse | alternate | alternate-reverse
733 </div>
735 <dl>
736 <dt><dfn>normal</dfn>
737 <dd>
738 All iterations of the animation are played as specified.
740 <dt><dfn>reverse</dfn>
741 <dd>
742 All iterations of the animation are played in the reverse direction from the way they were specified.
744 <dt><dfn>alternate</dfn>
745 <dd>
746 The animation cycle iterations that are odd counts are played in the normal direction,
747 and the animation cycle iterations that are even counts are played in a reverse direction.
749 <dt><dfn>alternate-reverse</dfn>
750 <dd>
751 The animation cycle iterations that are odd counts are played in the reverse direction,
752 and the animation cycle iterations that are even counts are played in a normal direction.
753 </dl>
755 <p class='note'>
756 Note that for the purpose of determining whether an iteration is even or odd,
757 iterations start counting from 1.
760 <h3 id="animation-play-state-property">
761 The 'animation-play-state' Property</h3>
763 <p>
764 The 'animation-play-state' property defines whether the animation is running or paused.
765 A running animation can be paused by setting this property to ''paused''.
766 To continue running a paused animation this property can be set to ''running''.
767 A paused animation will continue to display the current value of the animation in a static state,
768 as if the time of the animation is constant.
769 When a paused animation is resumed,
770 it restarts from the current value,
771 not necessarily from the beginning of the animation.
773 <table class=propdef>
774 <tr>
775 <th>Name:</th>
776 <td><dfn>animation-play-state</dfn>
777 <tr>
778 <th><a href="#values">Value</a>:
779 <td><span><single-animation-play-state></span> [ ',' <span><single-animation-play-state></span> ]*
780 <tr>
781 <th>Initial:
782 <td>''running''
783 <tr>
784 <th>Applies To:
785 <td>all elements
786 <tr>
787 <th>Inherited:
788 <td>no
789 <tr>
790 <th>Animatable:
791 <td>no
792 <tr>
793 <th>Percentages:
794 <td>N/A
795 <tr>
796 <th>Media:
797 <td>visual
798 <tr>
799 <th>Computed Value:
800 <td>as specified
801 <tr>
802 <th>Canonical Order:
803 <td><abbr title="follows order of property value definition">per grammar</abbr>
804 </table>
806 <div class="prod">
807 <dfn id="single-animation-play-state"><single-animation-play-state></dfn> =
808 running | paused
809 </div>
811 <h3 id="animation-delay-property">
812 The 'animation-delay' Property</h3>
814 <p>
815 The 'animation-delay' property defines when the animation will start.
816 It allows an animation to begin execution some time after it is applied.
817 An 'animation-delay' value of ''0s'' means the animation will execute as soon as it is applied.
818 Otherwise, the value specifies an offset from the moment the animation is applied,
819 and the animation will delay execution by that offset.
821 <p>
822 If the value for 'animation-delay' is a negative time offset
823 then the animation will execute the moment it is applied,
824 but will appear to have begun execution at the specified offset.
825 That is, the animation will appear to begin part-way through its play cycle.
826 In the case where an animation has implied starting values and a negative 'animation-delay',
827 the starting values are taken from the moment the animation is applied.
829 <table class=propdef>
830 <tr>
831 <th>Name:</th>
832 <td><dfn>animation-delay</dfn>
833 <tr>
834 <th><a href="#values">Value</a>:
835 <td> <span><time></span> [, <span><time></span>]*
836 <tr>
837 <th>Initial:
838 <td>''0s''
839 <tr>
840 <th>Applies To:
841 <td>all elements
842 <tr>
843 <th>Inherited:
844 <td>no
845 <tr>
846 <th>Animatable:
847 <td>no
848 <tr>
849 <th>Percentages:
850 <td>N/A
851 <tr>
852 <th>Media:
853 <td>visual
854 <tr>
855 <th>Computed Value:
856 <td>as specified
857 <tr>
858 <th>Canonical Order:
859 <td><abbr title="follows order of property value definition">per grammar</abbr>
860 </table>
863 <h3 id="animation-fill-mode-property">
864 The 'animation-fill-mode' Property</h3>
866 <p>
867 The 'animation-fill-mode' property defines what values are applied by the animation outside the time it is executing.
868 By default, an animation will not affect property values
869 between the time it is applied
870 (the 'animation-name' property is set on an element)
871 and the time it begins execution
872 (which is determined by the 'animation-delay' property).
873 Also, by default an animation does not affect property values after the animation ends
874 (determined by the 'animation-duration' property).
875 The 'animation-fill-mode' property can override this behavior.
877 <p>
878 If the value for 'animation-fill-mode' is ''backwards'',
879 then the animation will apply
880 the property values defined in the keyframe
881 that will start the first iteration of the animation,
882 during the period defined by 'animation-delay'.
883 These are either the values of the ''from'' keyframe
884 (when 'animation-direction' is ''normal'' or ''alternate'')
885 or those of the ''to'' keyframe
886 (when 'animation-direction' is ''reverse'' or ''alternate-reverse'').
888 <p>
889 If the value for 'animation-fill-mode' is ''forwards'',
890 then after the animation ends
891 (as determined by its 'animation-iteration-count'),
892 the animation will apply
893 the property values for the time the animation ended.
894 When 'animation-iteration-count' is an integer greater than zero,
895 the values applied will be
896 those for the end of the last completed iteration of the animation
897 (rather than the values for
898 the start of the iteration that would be next).
899 When 'animation-iteration-count' is zero,
900 the values applied will be those that would start the first iteration
901 (just as when 'animation-fill-mode' is ''backwards'').
903 <p>
904 If the value for 'animation-fill-mode' is ''both'',
905 then the animation will follow the rules for both 'forwards' and 'backwards'.
906 That is, it will extend the animation properties in both directions.
908 <table class=propdef>
909 <tr>
910 <th>Name:</th>
911 <td><dfn>animation-fill-mode</dfn>
912 <tr>
913 <th><a href="#values">Value</a>:
914 <td><span><single-animation-fill-mode></span> [ ',' <span><single-animation-fill-mode></span> ]*
915 <tr>
916 <th>Initial:
917 <td>''none''
918 <tr>
919 <th>Applies To:
920 <td>all elements
921 <tr>
922 <th>Inherited:
923 <td>no
924 <tr>
925 <th>Animatable:
926 <td>no
927 <tr>
928 <th>Percentages:
929 <td>N/A
930 <tr>
931 <th>Media:
932 <td>visual
933 <tr>
934 <th>Computed Value:
935 <td>as specified
936 <tr>
937 <th>Canonical Order:
938 <td><abbr title="follows order of property value definition">per grammar</abbr>
939 </table>
941 <div class="prod">
942 <dfn id="single-animation-fill-mode"><single-animation-fill-mode></dfn> =
943 none | forwards | backwards | both
944 </div>
946 <h3 id="animation-shorthand-property">
947 The 'animation' Shorthand Property
949 <p>
950 The 'animation' shorthand property combines seven of the animation properties into a single property.
952 <table class=propdef>
953 <tr>
954 <th>Name:</th>
955 <td><dfn>animation</dfn>
956 <tr>
957 <th><a href="#values">Value</a>:
958 <td><span><single-animation></span> [ ',' <span><single-animation></span> ]*
959 <tr>
960 <th>Initial:
961 <td>see individual properties
962 <tr>
963 <th>Applies To:
964 <td>all elements
965 <tr>
966 <th>Inherited:
967 <td>see individual properties
968 <tr>
969 <th>Animatable:
970 <td>no
971 <tr>
972 <th>Percentages:
973 <td>N/A
974 <tr>
975 <th>Media:
976 <td>visual
977 <tr>
978 <th>Computed Value:
979 <td>see individual properties
980 <tr>
981 <th>Canonical Order:
982 <td><abbr title="follows order of property value definition">per grammar</abbr>
983 </table>
985 <div class="prod">
986 <dfn id="single-animation"><single-animation></dfn> =
987 <single-animation-name> ||
988 <span><time></span> ||
989 <single-animation-timing-function> ||
990 <span><time></span> ||
991 <single-animation-iteration-count> ||
992 <single-animation-direction> ||
993 <single-animation-fill-mode>
994 </div>
996 <p>
997 Note that order is important within the items in this property:
998 the first value that can be parsed as a <var><time></var> is assigned to the
999 animation-duration,
1000 and the second value that can be parsed as a <var><time></var> is assigned to
1001 animation-delay.
1002 </p>
1004 <p class="issue">
1005 An alternative proposal is to accept the font shorthand approach
1006 of using a "/" character between the values of the same type.
1007 e.g. 2s/4s would mean a duration of 2 seconds and a delay of 4 seconds.
1009 <p class="issue">
1010 Need to also explain how order is important in terms of animation-name
1011 versus keywords, and probably also adjust the canonical order to
1012 match.
1014 <h2 id="animation-events">
1015 Animation Events</h2>
1017 <p>
1018 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>.
1019 The start and end of an animation,
1020 and the end of each iteration of an animation,
1021 all generate DOM events.
1022 An element can have multiple properties being animated simultaneously.
1023 This can occur either with a single 'animation-name' value
1024 with keyframes containing multiple properties,
1025 or with multiple 'animation-name' values.
1026 For the purposes of events,
1027 each 'animation-name' specifies a single animation.
1028 Therefore an event will be generated for each 'animation-name' value
1029 and not necessarily for each property being animated.
1031 <p>
1032 The time the animation has been running is sent with each event generated.
1033 This allows the event handler to determine the current iteration of a looping animation
1034 or the current position of an alternating animation.
1035 This time does not include any time the animation was in the ''paused'' play state.
1038 <h3 id='AnimationEvent-interface'>
1039 Interface <code>AnimationEvent</code>
1041 <p>
1042 The <dfn>AnimationEvent</dfn> interface provides specific contextual information associated with Animation events.
1045 <h4 id='AnimationEvent-IDL'>
1046 IDL Definition</h4>
1048 <pre class='idl'>
1049 interface AnimationEvent : Event {
1050 readonly attribute DOMString animationName;
1051 readonly attribute float elapsedTime;
1052 void initAnimationEvent(in DOMString typeArg,
1053 in boolean canBubbleArg,
1054 in boolean cancelableArg,
1055 in DOMString animationNameArg,
1056 in float elapsedTimeArg);
1057 };</pre>
1060 <h4 id='AnimationEvent-attributes'>
1061 Attributes</h4>
1063 <dl>
1064 <dt><code><dfn id='AnimationEvent-animationName'>animationName</dfn></code> of type <code>DOMString</code>, readonly
1065 <dd>
1066 The value of the 'animation-name' property of the animation that fired the event.
1068 <dt><code><dfn id='AnimationEvent-elapsedTime'>elapsedTime</dfn></code> of type <code>float</code>, readonly
1069 <dd>
1070 The amount of time the animation has been running,
1071 in seconds,
1072 when this event fired,
1073 excluding any time the animation was paused.
1074 For an "animationstart" event,
1075 the elapsedTime is zero unless there was a negative value for 'animation-delay',
1076 in which case the event will be fired with an <code>elapsedTime</code> of (-1 * delay).
1077 </dl>
1080 <h4 id='AnimationEvent-initAnimationMethod'>
1081 The <code>initAnimationEvent</code> method</h4>
1083 <p>
1084 The <dfn>initAnimationEvent</dfn> method is used to initialize the value of an <code>AnimationEvent</code>
1085 created through the <a href='http://www.w3.org/TR/DOM-Level-2-Events/events.html#Events-DocumentEvent'><code>DocumentEvent</code></a> interface.
1086 This method may only be called before the <code>AnimationEvent</code> has been dispatched
1087 via the <code>dispatchEvent</code> method,
1088 though it may be called multiple times during that phase if necessary.
1089 If called multiple times,
1090 the final invocation takes precedence.
1092 <p>
1093 Parameters:
1095 <dl>
1096 <dt><code>typeArg</code> of type <code>DOMString</code>
1097 <dd>
1098 Specifies the event type.
1100 <dt><code>canBubbleArg</code> of type <code>boolean</code>
1101 <dd>
1102 Specifies whether or not the event can bubble.<br>
1104 <dt><code>cancelableArg</code> of type <code>boolean</code>
1105 <dd>
1106 Specifies whether or not the event's default action can be prevented.
1108 <dt><code>animationNameArg</code> of type <code>DOMString</code>
1109 <dd>
1110 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>
1112 <dt><code>elapsedTimeArg</code> of type <code>float</code>
1113 <dd>
1114 Specifies the amount of time,
1115 in seconds,
1116 the animation has been running at the time of initialization.
1117 </dl>
1119 <p>
1120 No Return Value
1122 <p>
1123 No Exceptions
1125 <h3 id='AnimationEvent-types'>
1126 Types of <code>AnimationEvent</code></h3>
1128 <p>
1129 The different types of Animation events that can occur are:
1131 <dl>
1132 <dt><dfn>animationstart</dfn>
1133 <dd>
1134 The <code>animationstart</code> event occurs at the start of the animation.
1135 If there is an 'animation-delay'
1136 then this event will fire once the delay period has expired.
1137 A negative delay will cause the event to fire with an <code>elapsedTime</code> equal to the absolute value of the delay.
1139 <ul>
1140 <li>Bubbles: Yes
1141 <li>Cancelable: No
1142 <li>Context Info: animationName
1143 </ul>
1145 <dt><dfn>animationend</dfn>
1146 <dd>
1147 The <code>animationend</code> event occurs when the animation finishes.
1149 <ul>
1150 <li>Bubbles: Yes
1151 <li>Cancelable: No
1152 <li>Context Info: animationName, elapsedTime
1153 </ul>
1155 <dt><dfn>animationiteration</dfn>
1156 <dd>
1157 The <code>animationiteration</code> event occurs at the end of each iteration of an animation,
1158 except when an <code>animationend</code> event would fire at the same time.
1159 This means that this event does not occur for animations with an iteration count of one or less.
1161 <ul>
1162 <li>Bubbles: Yes
1163 <li>Cancelable: No
1164 <li>Context Info: animationName, elapsedTime
1165 </ul>
1166 </dl>
1169 <h2 id="dom-interfaces">
1170 DOM Interfaces</h2>
1172 <p>
1173 CSS animation is exposed to the CSSOM through a pair of new interfaces describing the keyframes.
1176 <h3 id='CSSRule-interface'>
1177 Interface <code>CSSRule</code></h3>
1179 <p>
1180 The following 2 rule types are added to the <dfn>CSSRule</dfn> interface.
1181 They provide identification for the new keyframe and keyframes rules.
1184 <h4 id='CSSRule-IDL'>
1185 IDL Definition</h4>
1187 <pre class='idl'>
1188 interface CSSRule {
1189 ...
1190 const unsigned short KEYFRAMES_RULE = 7;
1191 const unsigned short KEYFRAME_RULE = 8;
1192 ...
1193 };</pre>
1196 <h3 id='CSSKeyframeRule-interface'>
1197 Interface <code>CSSKeyframeRule</code></3h>
1198 <p>
1199 The <dfn>CSSKeyframeRule</dfn> interface represents the style rule for a single key.
1202 <h4 id='CSSKeyframeRule-IDL'>
1203 IDL Definition</h4>
1205 <pre class='idl'>
1206 interface CSSKeyframeRule : CSSRule {
1207 attribute DOMString keyText;
1208 readonly attribute CSSStyleDeclaration style;
1209 };</pre>
1212 <h4 id='CSSKeyframeRule-attributes'>
1213 Attributes</h4>
1215 <dl>
1216 <dt><code><dfn id='CSSKeyframeRule-keyText'>keyText</dfn></code> of type <code>DOMString</code>
1217 <dd>
1218 This attribute represents the key
1219 as the string representation of a floating point number between 0 and 1.
1220 If the value in the CSS style is ''from''
1221 this value will be 0,
1222 and if the value in the CSS style is ''to''
1223 this value will be 1.
1225 <dt><code><dfn id='CSSKeyframeRule-style'>style</dfn></code> of type <code>CSSStyleDeclaration</code>
1226 <dd>
1227 This attribute represents the style associated with this keyframe.
1228 </dl>
1231 <h3 id='CSSKeyframesRule-interface'>
1232 Interface <code>CSSKeyframesRule</code></h3>
1234 <p>
1235 The <dfn>CSSKeyframesRule</dfn> interface represents a complete set of keyframes for a single animation.
1238 <h4 id='CSSKeyframesRule-IDL'>
1239 IDL Definition</h4>
1241 <pre class='idl'>
1242 interface CSSKeyframesRule : CSSRule {
1243 attribute DOMString name;
1244 readonly attribute CSSRuleList cssRules;
1246 void appendRule(in DOMString rule);
1247 void deleteRule(in DOMString key);
1248 CSSKeyframeRule findRule(in DOMString key);
1249 };</pre>
1252 <h4 id='CSSKeyframesRule-attributes'>
1253 Attributes</h4>
1255 <dl>
1256 <dt><code><dfn id='CSSKeyframesRule-name'>name</dfn></code> of type <code>DOMString</code>
1257 <dd>
1258 This attribute is the name of the keyframes, used by the 'animation-name' property.<br>
1260 <dt><code><dfn id='CSSKeyframesRules-cssRules'>cssRules</dfn></code> of type <code>CSSRuleList</code>
1261 <dd>
1262 This attribute gives access to the keyframes in the list.
1265 <h4 id='CSSKeyframesRule-appendRule'>
1266 The <code>appendRule</code> method</h4>
1268 <p>
1269 The <dfn>appendRule</dfn> method appends the passed CSSKeyframeRule into the list at the passed key.
1271 <p>
1272 Parameters:
1274 <dl>
1275 <dt><code>rule</code> of type <code>DOMString</code>
1277 <dd>
1278 The rule to be appended,
1279 expressed in the same syntax as one entry in the ''@keyframes'' rule.
1280 </dl>
1282 <p>
1283 No Return Value
1285 <p>
1286 No Exceptions
1289 <h4 id='CSSKeyframesRules-deleteRule'>
1290 The <code>deleteRule</code> method</h4>
1292 <p>
1293 The <dfn>deleteRule</dfn> method deletes the CSSKeyframeRule with the passed key.
1294 If a rule with this key does not exist,
1295 the method does nothing.
1297 <p>
1298 Parameters:
1300 <dl>
1301 <dt><code>key</code> of type <code>DOMString</code>
1302 <dd>
1303 The key which describes the rule to be deleted.
1304 The key must resolve to a number between 0 and 1,
1305 or the rule is ignored.
1306 </dl>
1308 <p>
1309 No Return Value
1311 <p>
1312 No Exceptions
1315 <h4 id='CSSKeyframesRule-findRule'>
1316 The <code>findRule</code> method</h4>
1318 <p>
1319 The <code>findRule</code> method returns the rule with a key matching the passed key.
1320 If no such rule exists,
1321 a null value is returned.
1323 <p>
1324 Parameters:
1326 <dl>
1327 <dt><code>key</code> of type <code>DOMString</code>
1328 <dd>
1329 The key which described the rule to find.
1330 The key must resolve to a number between 0 and 1,
1331 or the rule is ignored.
1332 </dl>
1334 <p>
1335 Return Value:
1337 <dl>
1338 <dt><code>CSSKeyframeRule</code>
1339 <dd>
1340 The found rule.
1341 </dl>
1343 <p>
1344 No Exceptions
1347 <h2 id="acknowledgments">Acknowledgments</h2>
1349 <p>Thanks especially to the feedback from
1350 Tab Atkins,
1351 Carine Bournez,
1352 Estelle Weyl,
1353 and all the rest of the
1354 <a href="http://lists.w3.org/Archives/Public/www-style/">www-style</a> community.
1356 <h2>References</h2>
1358 <h3 class="no-num">Normative references</h3>
1359 <!--normative-->
1361 <h3 class="no-num">Other references</h3>
1362 <!--informative-->
1366 <h2 class="no-num">Property index</h2>
1367 <!-- properties -->
1371 <h2 class="no-num" id="index">Index</h2>
1372 <!--index-->
1374 </body>
1375 </html>
1376 <!-- Keep this comment at the end of the file
1377 Local variables:
1378 mode: sgml
1379 sgml-declaration:"~/SGML/HTML4.decl"
1380 sgml-default-doctype-name:"html"
1381 sgml-minimize-attributes:t
1382 sgml-nofill-elements:("pre" "style" "br")
1383 sgml-live-element-indicator:t
1384 sgml-omittag:nil
1385 sgml-shorttag:nil
1386 sgml-namecase-general:t
1387 sgml-general-insert-case:lower
1388 sgml-always-quote-attributes:t
1389 sgml-indent-step:nil
1390 sgml-indent-data:t
1391 sgml-parent-document:nil
1392 sgml-exposed-tags:nil
1393 sgml-local-catalogs:nil
1394 sgml-local-ecat-files:nil
1395 End:
1396 -->
