css3-animations/Overview.src.html@802063087266
css3-animations/Overview.src.html
Sun, 10 Feb 2013 00:40:56 -0800
- author
- L. David Baron <dbaron@dbaron.org>
- date
- Sun, 10 Feb 2013 00:40:56 -0800
- changeset 7423
- 802063087266
- parent 7407
- 267f78f1b645
- child 7452
- 58e0d9206d99
- permissions
- -rw-r--r--
[css3-animations][css3-transitions] Make naming of event constructor dictionary parameters more consistent with DOM-Level-3-Events.
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.
114 <h2 id="values">
115 Values</h2>
117 <p>
118 This specification follows the <a href="http://www.w3.org/TR/CSS21/about.html#property-defs">CSS property definition conventions</a> from [[!CSS21]].
119 Value types not defined in this specification are defined in CSS Level 2 Revision 1 [[!CSS21]].
120 Other CSS modules may expand the definitions of these value types:
121 for example [[CSS3VAL]], when combined with this module,
122 expands the definition of the <var><length></var> value type as used in this specification.
124 <p>In addition to the property-specific values listed in their definitions, all properties defined in this specification also accept the <a href="http://dev.w3.org/csswg/css3-values/#common-keywords">''initial''</a> and <a href="http://dev.w3.org/csswg/css3-values/#common-keywords">''inherit''</a> keyword as their property value. For readability it has not been repeated explicitly.
127 <h2 id="animations">
128 Animations</h2>
130 <p>
131 CSS Animations affect computed property values.
132 During the execution of an animation,
133 the computed value for a property is controlled by the animation.
134 This overrides the value specified in the normal styling system.
135 Animations override all normal rules, but are overriden by
136 !important rules.
138 <p>
139 If at one point in time there are multiple animations specifying behavior for the same property,
140 the animation whose name occurs last in the value of 'animation-name'
141 will override the other animations at that point.
144 <p>
145 An animation does not affect the computed value before the application of the animation,
146 before the animation delay has expired,
147 and after the end of the animation.
150 <div class="figure">
151 <img src="sandwich.png" alt="">
153 <p class="caption">
154 Computation of animated property values
155 </div>
157 <p>
158 The diagram above shows how property values are computed.
159 The intrinsic style is shown at the top of the diagram.
160 The computed value is derived from intrinsic style
161 at the times when an animation is not running
162 and also when an animation is delayed
163 (see below for specification of animation delay).
164 During an animation,
165 the computed style is derived from the animated value.
168 <p>
169 The start time of an animation is the latter of two moments:
170 the time at which the style is resolved that specifies the animation,
171 or the time the document's load event is fired.
172 Therefore, an animation specified in the document style sheet
173 will begin at the document load.
174 An animation specified on an element by modifying the style after the document has loaded
175 will start when the style is resolved.
176 That may be immediately in the case of a pseudo style rule such as hover,
177 or may be when the scripting engine returns control to the browser
178 (in the case of style applied by script).
181 <p>
182 An animation applies to an element
183 if the element has a value for 'animation-name' that references a valid keyframes rule.
184 Once an animation has started
185 it continues until it ends
186 or the 'animation-name' is removed.
187 The values used for the keyframes and animation properties are snapshotted at the time the animation starts.
188 Changing them during the execution of the animation has no effect.
189 Note also that changing the value of 'animation-name' does not necessarily restart an animation
190 (e.g., if a list of animations are applied and one is removed from the list,
191 only that animation will stop;
192 The other animations will continue).
193 In order to restart an animation,
194 it must be removed then reapplied.
197 <p>
198 The end of the animation is defined by the combination of the
199 'animation-duration',
200 'animation-iteration-count' and
201 'animation-fill-mode' properties.
204 <div class="example">
205 <pre>
206 div {
207 animation-name: diagonal-slide;
208 animation-duration: 5s;
209 animation-iteration-count: 10;
210 }
212 @keyframes diagonal-slide {
214 from {
215 left: 0;
216 top: 0;
217 }
219 to {
220 left: 100px;
221 top: 100px;
222 }
224 }</pre>
226 <p>
227 This will produce an animation
228 that moves an element from (0, 0) to (100px, 100px)
229 over five seconds
230 and repeats itself nine times
231 (for a total of ten iterations).
232 </div>
234 <p>
235 Setting the display property to 'none' will terminate any running animation
236 applied to the element and its descendants.
238 If an element has a display of 'none', updating display to a value other than 'none'
239 will start all animations applied to the element by the 'animation-name' property,
240 as well as all animations applied to descendants with display other than 'none'.
241 </p>
243 <p>
244 While authors can use animations to create dynamically changing content,
245 dynamically changing content can lead to seizures in some users.
246 For information on how to avoid content that can lead to seizures, see
247 <a href="http://www.w3.org/TR/WCAG20/#seizure">Guideline 2.3:
248 Seizures:
249 Do not design content in a way that is known to cause seizures</a>
250 ([[WCAG20]]).
251 </p>
253 <h2 id="keyframes">
254 Keyframes</h2>
255 <p>
256 Keyframes are used to specify the values for the animating properties
257 at various points during the animation.
258 The keyframes specify the behavior of one cycle of the animation;
259 the animation may iterate one or more times.
261 <p>
262 Keyframes are specified using a specialized CSS at-rule.
263 A @keyframes rule consists of the keyword "@keyframes",
264 followed by an identifier giving a name for the animation
265 (which will be referenced using 'animation-name'),
266 followed by a set of style rules
267 (delimited by curly braces).
269 <p>
270 The <dfn>keyframe selector</dfn> for a keyframe style rule
271 consists of a comma-separated list of percentage values
272 or the keywords 'from' or 'to'.
273 The selector is used to specify the percentage along the duration of the animation that the keyframe represents.
274 The keyframe itself is specified by the block of property values declared on the selector.
275 The keyword 'from' is equivalent to the value ''0%''.
276 The keyword 'to' is equivalent to the value ''100%''.
277 <span class='note'>Note that the percentage unit specifier must be used on percentage values.
278 Therefore, ''0'' is an invalid keyframe selector.</span>
280 <p>
281 If a ''0%'' or ''from'' keyframe is not specified,
282 then the user agent constructs a ''0%'' keyframe
283 using the computed values of the properties being animated.
284 If a ''100%'' or ''to'' keyframe is not specified,
285 then the user agent constructs a ''100%'' keyframe
286 using the computed values of the properties being animated.
287 If a keyframe selector specifies
288 negative percentage values or
289 values higher than 100%,
290 then the keyframe will be ignored.
292 <p>
293 The <dfn>keyframe declaration block</dfn> for a keyframe rule
294 consists of properties and values.
295 Properties that are unable to be animated are ignored in these rules,
296 with the exception of 'animation-timing-function',
297 the behavior of which is described below. In addition, keyframe rule declarations qualified with !important are ignored.
299 <p class="issue">
300 Need to describe what happens if a property is not present in all keyframes.
302 <p>
303 The @keyframes rule that is used by an animation
304 will be the last one encountered in sorted rules order
305 that matches the name of the animation specified by the 'animation-name' property.
306 @keyframes rules do not cascade;
307 therefore, an animation will never derive keyframes from more than one @keyframes rule.
309 <p class='note'>
310 Note that since empty @keyframes rule are valid, they may hide the keyframes of
311 those preceding animation definitions with a matching name.
313 <p>
314 To determine the set of keyframes,
315 all of the values in the selectors are sorted in increasing order by time.
316 If there are any duplicates,
317 then the last keyframe specified inside the @keyframes rule
318 will be used to provide the keyframe information for that time.
319 There is no cascading within a @keyframes rule if multiple keyframes specify the same keyframe selector values.
321 <p>
322 If a property is not specified for a keyframe,
323 or is specified but invalid,
324 the animation of that property proceeds as if that keyframe did not exist.
325 Conceptually,
326 it is as if a set of keyframes is constructed for each property that is present in any of the keyframes,
327 and an animation is run independently for each property.
329 <div class="example">
330 <pre>
331 @keyframes wobble {
332 0% {
333 left: 100px;
334 }
336 40% {
337 left: 150px;
338 }
340 60% {
341 left: 75px;
342 }
344 100% {
345 left: 100px;
346 }
347 }</pre>
349 <p>
350 Four keyframes are specified for the animation named "wobble".
351 In the first keyframe,
352 shown at the beginning of the animation cycle,
353 the value of the 'left' property being animated is ''100px''.
354 By 40% of the animation duration,
355 'left' has animated to ''150px''.
356 At 60% of the animation duration,
357 'left' has animated back to ''75px''.
358 At the end of the animation cycle,
359 the value of 'left' has returned to ''100px''.
360 The diagram below shows the state of the animation if it were given a duration of ''10s''.
362 <div class="figure">
363 <img src="animation1.png" alt="">
365 <p class="caption">
366 Animations states specified by keyframes
367 </div>
368 </div>
370 <p>
371 The following is the grammar for the keyframes rule.
373 <pre>
374 keyframes_rule: KEYFRAMES_SYM S+ IDENT S* '{' S* keyframes_blocks '}' S*;
376 keyframes_blocks: [ keyframe_selector '{' S* declaration? [ ';' S* declaration? ]* '}' S* ]* ;
378 keyframe_selector: [ FROM_SYM | TO_SYM | PERCENTAGE ] S* [ ',' S* [ FROM_SYM | TO_SYM | PERCENTAGE ] S* ]*;
380 @{K}{E}{Y}{F}{R}{A}{M}{E}{S} {return KEYFRAMES_SYM;}
381 {F}{R}{O}{M} {return FROM_SYM;}
382 {T}{O} {return TO_SYM;}</pre>
385 <h3 id="timing-functions">
386 Timing functions for keyframes</h3>
388 <p>
389 A keyframe style rule may also declare the timing function that is to be used
390 as the animation moves to the next keyframe.
392 <div class="example">
393 <pre>
394 @keyframes bounce {
396 from {
397 top: 100px;
398 animation-timing-function: ease-out;
399 }
401 25% {
402 top: 50px;
403 animation-timing-function: ease-in;
404 }
406 50% {
407 top: 100px;
408 animation-timing-function: ease-out;
409 }
411 75% {
412 top: 75px;
413 animation-timing-function: ease-in;
414 }
416 to {
417 top: 100px;
418 }
420 }</pre>
422 <p>
423 Five keyframes are specified for the animation named "bounce".
424 Between the first and second keyframe
425 (i.e., between 0% and 25%)
426 an ''ease-out'' timing function is used.
427 Between the second and third keyframe
428 (i.e., between 25% and 50%)
429 an ''ease-in'' timing function is used.
430 And so on.
431 The effect will appear as an element that moves up the page ''50px'',
432 slowing down as it reaches its highest point
433 then speeding up as it falls back to ''100px''.
434 The second half of the animation behaves in a similar manner,
435 but only moves the element ''25px'' up the page.
436 </div>
438 <p>
439 A timing function specified on the "to" or 100% keyframe is ignored.
441 <p>
442 See the 'animation-timing-function' property for more information.
445 <h3 id="animation-name-property">
446 The 'animation-name' Property</h3>
448 <p>
449 The 'animation-name' property defines a list of animations that apply.
450 Each name is used to select the keyframe at-rule
451 that provides the property values for the animation.
452 If the name does not match any keyframe at-rule,
453 there are no properties to be animated
454 and the animation will not execute.
455 Furthermore,
456 if the animation name is ''none''
457 then there will be no animation.
458 This can be used to override any animations coming from the cascade.
459 If multiple animations are attempting to modify the same property,
460 then the animation closest to the end of the list of names wins.
462 <p id="list-matching">
463 Each animation listed by name
464 should have a corresponding value for the other animation properties listed below.
465 If the lists of values for the other animation properties do not have the same length,
466 the length of the 'animation-name' list
467 determines the number of items in each list examined when starting animations.
468 The lists are matched up from the first value:
469 excess values at the end are not used.
470 If one of the other properties doesn't have enough comma-separated values to match the number of values of 'animation-name',
471 the UA must calculate its used value by repeating the list of values until there are enough.
472 This truncation or repetition does not affect the computed value.
473 <span class="note">Note: This is analogous to the behavior of the 'background-*'properties,
474 with 'background-image' analogous to 'animation-name'.</span>
477 <table class=propdef>
478 <tr>
479 <th>Name:</th>
480 <td><dfn>animation-name</dfn>
481 <tr>
482 <th><a href="#values">Value</a>:
483 <td><span><single-animation-name></span> [ ',' <span><single-animation-name></span> ]*
484 <tr>
485 <th>Initial:
486 <td>''none''
487 <tr>
488 <th>Applies To:
489 <td>all elements, ::before and ::after pseudo-elements
490 <tr>
491 <th>Inherited:
492 <td>no
493 <tr>
494 <th>Animatable:
495 <td>no
496 <tr>
497 <th>Percentages:
498 <td>N/A
499 <tr>
500 <th>Media:
501 <td>visual
502 <tr>
503 <th>Computed Value:
504 <td>As specified
505 <tr>
506 <th>Canonical Order:
507 <td><abbr title="follows order of property value definition">per grammar</abbr>
508 </table>
510 <div class="prod">
511 <dfn id="single-animation-name"><single-animation-name></dfn> = none | <IDENT>
512 </div>
514 <!--
515 <p>
516 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.
518 <div class="example">
519 <p style="display:none">
520 Example(s):
522 <pre>
523 @keyframes 'border-bloat' {
524 from {
525 border-width: 0;
526 }
527 to {
528 border-width: 10px;
529 }
530 }
532 @keyframes 'border-diet' {
533 from {
534 border-width: 4px;
535 }
536 to {
537 border-width: 2px;
538 }
539 }
541 div {
542 animation-name: 'border-bloat', 'border-diet';
543 animation-duration: 10s, 4s;
544 }
545 </pre>
546 <p>
547 The above example has two animations executing on the same property, 'border-width'. The animations are additive. That is, the
548 resulting value for the property will be the addition of the values from the
549 two animations.
551 <p>
552 At time '0s' the element's border will be 4px wide (0px from 'border-bloat' plus 4px from 'border-diet').
553 At time '4s' the element's border will be 6px wide (4px from 'border-bloat' plus 2px from 'border-diet').
554 At time '10s' the element's border will be 10px wide (10px from 'border-bloat' and no addition from
555 'border-diet' as it is no longer executing).
557 </div>
558 -->
561 <h3 id="animation-duration-property">
562 The 'animation-duration' Property</h3>
564 <p>
565 The 'animation-duration' property defines the length of time that an animation takes to complete one cycle.
568 <table class=propdef>
569 <tr>
570 <th>Name:</th>
571 <td><dfn>animation-duration</dfn>
572 <tr>
573 <th><a href="#values">Value</a>:
574 <td> <span><time></span> [, <span><time></span>]*
575 <tr>
576 <th>Initial:
577 <td>''0s''
578 <tr>
579 <th>Applies To:
580 <td>all elements, ::before and ::after pseudo-elements
581 <tr>
582 <th>Inherited:
583 <td>no
584 <tr>
585 <th>Animatable:
586 <td>no
587 <tr>
588 <th>Percentages:
589 <td>N/A
590 <tr>
591 <th>Media:
592 <td>visual
593 <tr>
594 <th>Computed Value:
595 <td>as specified
596 <tr>
597 <th>Canonical Order:
598 <td><abbr title="follows order of property value definition">per grammar</abbr>
599 </table>
601 <p>
602 The initial value is ''0s'',
603 meaning that the animation takes no time.
604 When the duration is ''0s'' 'animation-fill-mode' still applies,
605 so an animation that fills backwards
606 will show the value of the 0% keyframe during any delay period,
607 and an animation that fills forwards will retain the value specified at the 100% keyframe,
608 even if the animation was instantaneous.
609 Also, animation events are still fired.
610 A negative 'animation-duration' value renders the declaration invalid.
613 <h3 id="animation-timing-function-property">
614 The 'animation-timing-function' Property</h3>
616 <p>
617 The 'animation-timing-function' property describes how the animation will progress over one cycle of its duration.
618 See the 'transition-timing-function' property [[!CSS3-TRANSITIONS]] for a complete description of timing function calculation.
620 <table class=propdef>
621 <tr>
622 <th>Name:</th>
623 <td><dfn>animation-timing-function</dfn>
624 <tr>
625 <th><a href="#values">Value</a>:
626 <td><span><single-timing-function></span> [ ',' <span><single-timing-function></span> ]*
627 <tr>
628 <th>Initial:
629 <td>''ease''
630 <tr>
631 <th>Applies To:
632 <td>all elements, ::before and ::after pseudo-elements
633 <tr>
634 <th>Inherited:
635 <td>no
636 <tr>
637 <th>Animatable:
638 <td>no
639 <tr>
640 <th>Percentages:
641 <td>N/A
642 <tr>
643 <th>Media:
644 <td>visual
645 <tr>
646 <th>Computed Value:
647 <td>as specified
648 <tr>
649 <th>Canonical Order:
650 <td><abbr title="follows order of property value definition">per grammar</abbr>
651 </table>
653 <p>All the valid values of ''<single-timing-function>'' are defined by the 'transition-timing-function' property [[!CSS3-TRANSITIONS]].</p>
655 <p>
656 For a keyframed animation,
657 the 'animation-timing-function' applies between keyframes,
658 not over the entire animation.
659 For example,
660 in the case of an ''ease-in-out'' timing function,
661 an animation will ease in at the start of the keyframe
662 and ease out at the end of the keyframe.
663 An 'animation-timing-function' defined within a keyframe block applies to that keyframe,
664 otherwise the timing function specified for the animation is used.
667 <h3 id="animation-iteration-count-property">
668 The 'animation-iteration-count' Property</h3>
670 <p>
671 The 'animation-iteration-count' property specifies the number of times an animation cycle is played.
672 The initial value is ''1'',
673 meaning the animation will play from beginning to end once.
674 A value of ''infinite'' will cause the animation to repeat forever.
675 Non-integer numbers will cause the animation to end part-way through a cycle.
676 Negative values of 'animation-iteration-count' are invalid.
677 This property is often used in conjunction an 'animation-direction' value of ''alternate'',
678 which will cause the animation to play in reverse on alternate cycles.
680 <table class=propdef>
681 <tr>
682 <th>Name:</th>
683 <td><dfn>animation-iteration-count</dfn>
684 <tr>
685 <th><a href="#values">Value</a>:
686 <td><span><single-animation-iteration-count></span> [ ',' <span><single-animation-iteration-count></span> ]*
687 <tr>
688 <th>Initial:
689 <td>''1''
690 <tr>
691 <th>Applies To:
692 <td>all elements, ::before and ::after pseudo-elements
693 <tr>
694 <th>Inherited:
695 <td>no
696 <tr>
697 <th>Animatable:
698 <td>no
699 <tr>
700 <th>Percentages:
701 <td>N/A
702 <tr>
703 <th>Media:
704 <td>visual
705 <tr>
706 <th>Computed Value:
707 <td>as specified
708 <tr>
709 <th>Canonical Order:
710 <td><abbr title="follows order of property value definition">per grammar</abbr>
711 </table>
713 <div class="prod">
714 <dfn id="single-animation-iteration-count"><single-animation-iteration-count></dfn> =
715 infinite | <number>
716 </div>
718 <h3 id="animation-direction-property">
719 The 'animation-direction' Property</h3>
721 <p>
722 The 'animation-direction' property defines whether or not the animation should play in reverse on some or all cycles.
723 When an animation is played in reverse the timing functions are also reversed.
724 For example, when played in reverse an ease-in animation would appear to be an ease-out animation.
726 <table class=propdef>
727 <tr>
728 <th>Name:</th>
729 <td><dfn>animation-direction</dfn>
730 <tr>
731 <th><a href="#values">Value</a>:
732 <td><span><single-animation-direction></span> [ ',' <span><single-animation-direction></span> ]*
733 <tr>
734 <th>Initial:
735 <td>''normal''
736 <tr>
737 <th>Applies To:
738 <td>all elements, ::before and ::after pseudo-elements
739 <tr>
740 <th>Inherited:
741 <td>no
742 <tr>
743 <th>Animatable:
744 <td>no
745 <tr>
746 <th>Percentages:
747 <td>N/A
748 <tr>
749 <th>Media:
750 <td>visual
751 <tr>
752 <th>Computed Value:
753 <td>as specified
754 <tr>
755 <th>Canonical Order:
756 <td><abbr title="follows order of property value definition">per grammar</abbr>
757 </table>
759 <div class="prod">
760 <dfn id="single-animation-direction"><single-animation-direction></dfn> =
761 normal | reverse | alternate | alternate-reverse
762 </div>
764 <dl>
765 <dt><dfn>normal</dfn>
766 <dd>
767 All iterations of the animation are played as specified.
769 <dt><dfn>reverse</dfn>
770 <dd>
771 All iterations of the animation are played in the reverse direction from the way they were specified.
773 <dt><dfn>alternate</dfn>
774 <dd>
775 The animation cycle iterations that are odd counts are played in the normal direction,
776 and the animation cycle iterations that are even counts are played in a reverse direction.
778 <dt><dfn>alternate-reverse</dfn>
779 <dd>
780 The animation cycle iterations that are odd counts are played in the reverse direction,
781 and the animation cycle iterations that are even counts are played in a normal direction.
782 </dl>
784 <p class='note'>
785 Note that for the purpose of determining whether an iteration is even or odd,
786 iterations start counting from 1.
789 <h3 id="animation-play-state-property">
790 The 'animation-play-state' Property</h3>
792 <p>
793 The 'animation-play-state' property defines whether the animation is running or paused.
794 A running animation can be paused by setting this property to ''paused''.
795 To continue running a paused animation this property can be set to ''running''.
796 A paused animation will continue to display the current value of the animation in a static state,
797 as if the time of the animation is constant.
798 When a paused animation is resumed,
799 it restarts from the current value,
800 not necessarily from the beginning of the animation.
802 <table class=propdef>
803 <tr>
804 <th>Name:</th>
805 <td><dfn>animation-play-state</dfn>
806 <tr>
807 <th><a href="#values">Value</a>:
808 <td><span><single-animation-play-state></span> [ ',' <span><single-animation-play-state></span> ]*
809 <tr>
810 <th>Initial:
811 <td>''running''
812 <tr>
813 <th>Applies To:
814 <td>all elements, ::before and ::after pseudo-elements
815 <tr>
816 <th>Inherited:
817 <td>no
818 <tr>
819 <th>Animatable:
820 <td>no
821 <tr>
822 <th>Percentages:
823 <td>N/A
824 <tr>
825 <th>Media:
826 <td>visual
827 <tr>
828 <th>Computed Value:
829 <td>as specified
830 <tr>
831 <th>Canonical Order:
832 <td><abbr title="follows order of property value definition">per grammar</abbr>
833 </table>
835 <div class="prod">
836 <dfn id="single-animation-play-state"><single-animation-play-state></dfn> =
837 running | paused
838 </div>
840 <h3 id="animation-delay-property">
841 The 'animation-delay' Property</h3>
843 <p>
844 The 'animation-delay' property defines when the animation will start.
845 It allows an animation to begin execution some time after it is applied.
846 An 'animation-delay' value of ''0s'' means the animation will execute as soon as it is applied.
847 Otherwise, the value specifies an offset from the moment the animation is applied,
848 and the animation will delay execution by that offset.
850 <p>
851 If the value for 'animation-delay' is a negative time offset
852 then the animation will execute the moment it is applied,
853 but will appear to have begun execution at the specified offset.
854 That is, the animation will appear to begin part-way through its play cycle.
855 In the case where an animation has implied starting values and a negative 'animation-delay',
856 the starting values are taken from the moment the animation is applied.
858 <table class=propdef>
859 <tr>
860 <th>Name:</th>
861 <td><dfn>animation-delay</dfn>
862 <tr>
863 <th><a href="#values">Value</a>:
864 <td> <span><time></span> [, <span><time></span>]*
865 <tr>
866 <th>Initial:
867 <td>''0s''
868 <tr>
869 <th>Applies To:
870 <td>all elements, ::before and ::after pseudo-elements
871 <tr>
872 <th>Inherited:
873 <td>no
874 <tr>
875 <th>Animatable:
876 <td>no
877 <tr>
878 <th>Percentages:
879 <td>N/A
880 <tr>
881 <th>Media:
882 <td>visual
883 <tr>
884 <th>Computed Value:
885 <td>as specified
886 <tr>
887 <th>Canonical Order:
888 <td><abbr title="follows order of property value definition">per grammar</abbr>
889 </table>
892 <h3 id="animation-fill-mode-property">
893 The 'animation-fill-mode' Property</h3>
895 <p>
896 The 'animation-fill-mode' property defines what values are applied by the animation outside the time it is executing.
897 By default, an animation will not affect property values
898 between the time it is applied
899 (the 'animation-name' property is set on an element)
900 and the time it begins execution
901 (which is determined by the 'animation-delay' property).
902 Also, by default an animation does not affect property values after the animation ends
903 (determined by the 'animation-duration' property).
904 The 'animation-fill-mode' property can override this behavior.
906 <p>
907 If the value for 'animation-fill-mode' is ''backwards'',
908 then the animation will apply
909 the property values defined in the keyframe
910 that will start the first iteration of the animation,
911 during the period defined by 'animation-delay'.
912 These are either the values of the ''from'' keyframe
913 (when 'animation-direction' is ''normal'' or ''alternate'')
914 or those of the ''to'' keyframe
915 (when 'animation-direction' is ''reverse'' or ''alternate-reverse'').
917 <p>
918 If the value for 'animation-fill-mode' is ''forwards'',
919 then after the animation ends
920 (as determined by its 'animation-iteration-count'),
921 the animation will apply
922 the property values for the time the animation ended.
923 When 'animation-iteration-count' is an integer greater than zero,
924 the values applied will be
925 those for the end of the last completed iteration of the animation
926 (rather than the values for
927 the start of the iteration that would be next).
928 When 'animation-iteration-count' is zero,
929 the values applied will be those that would start the first iteration
930 (just as when 'animation-fill-mode' is ''backwards'').
932 <p>
933 If the value for 'animation-fill-mode' is ''both'',
934 then the animation will follow the rules for both 'forwards' and 'backwards'.
935 That is, it will extend the animation properties in both directions.
937 <table class=propdef>
938 <tr>
939 <th>Name:</th>
940 <td><dfn>animation-fill-mode</dfn>
941 <tr>
942 <th><a href="#values">Value</a>:
943 <td><span><single-animation-fill-mode></span> [ ',' <span><single-animation-fill-mode></span> ]*
944 <tr>
945 <th>Initial:
946 <td>''none''
947 <tr>
948 <th>Applies To:
949 <td>all elements, ::before and ::after pseudo-elements
950 <tr>
951 <th>Inherited:
952 <td>no
953 <tr>
954 <th>Animatable:
955 <td>no
956 <tr>
957 <th>Percentages:
958 <td>N/A
959 <tr>
960 <th>Media:
961 <td>visual
962 <tr>
963 <th>Computed Value:
964 <td>as specified
965 <tr>
966 <th>Canonical Order:
967 <td><abbr title="follows order of property value definition">per grammar</abbr>
968 </table>
970 <div class="prod">
971 <dfn id="single-animation-fill-mode"><single-animation-fill-mode></dfn> =
972 none | forwards | backwards | both
973 </div>
975 <h3 id="animation-shorthand-property">
976 The 'animation' Shorthand Property
978 <p>
979 The 'animation' shorthand property is a comma-separated list of
980 animation definitions, each of which combines seven of the animation properties
981 into a single component value.
983 <table class=propdef>
984 <tr>
985 <th>Name:</th>
986 <td><dfn>animation</dfn>
987 <tr>
988 <th><a href="#values">Value</a>:
989 <td><span><single-animation></span> [ ',' <span><single-animation></span> ]*
990 <tr>
991 <th>Initial:
992 <td>see individual properties
993 <tr>
994 <th>Applies To:
995 <td>all elements, ::before and ::after pseudo-elements
996 <tr>
997 <th>Inherited:
998 <td>see individual properties
999 <tr>
1000 <th>Animatable:
1001 <td>no
1002 <tr>
1003 <th>Percentages:
1004 <td>N/A
1005 <tr>
1006 <th>Media:
1007 <td>visual
1008 <tr>
1009 <th>Computed Value:
1010 <td>see individual properties
1011 <tr>
1012 <th>Canonical Order:
1013 <td><abbr title="follows order of property value definition">per grammar</abbr>
1014 </table>
1016 <div class="prod">
1017 <dfn id="single-animation"><single-animation></dfn> =
1018 <single-animation-name> ||
1019 <span><time></span> ||
1020 <single-animation-timing-function> ||
1021 <span><time></span> ||
1022 <single-animation-iteration-count> ||
1023 <single-animation-direction> ||
1024 <single-animation-fill-mode> ||
1025 <single-animation-play-state>
1026 </div>
1028 <p>
1029 Note that order is important within each animation definition:
1030 the first value that can be parsed as a <var><time></var> is assigned to the
1031 animation-duration,
1032 and the second value that can be parsed as a <var><time></var> is assigned to
1033 animation-delay.
1034 </p>
1036 <p class="issue">
1037 An alternative proposal is to accept the font shorthand approach
1038 of using a "/" character between the values of the same type.
1039 e.g. 2s/4s would mean a duration of 2 seconds and a delay of 4 seconds.
1041 <p class="issue">
1042 Need to also explain how order is important in terms of animation-name
1043 versus keywords, and probably also adjust the canonical order to
1044 match.
1046 <h2 id="animation-events">
1047 Animation Events</h2>
1049 <p>
1050 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>.
1051 The start and end of an animation,
1052 and the end of each iteration of an animation,
1053 all generate DOM events.
1054 An element can have multiple properties being animated simultaneously.
1055 This can occur either with a single 'animation-name' value
1056 with keyframes containing multiple properties,
1057 or with multiple 'animation-name' values.
1058 For the purposes of events,
1059 each 'animation-name' specifies a single animation.
1060 Therefore an event will be generated for each 'animation-name' value
1061 and not necessarily for each property being animated.
1063 <p>
1064 Any animation for which both a valid keyframe rule and a non-zero duration are
1065 defined will run and generate events; this includes animations with empty
1066 keyframe rules.
1068 <p>
1069 The time the animation has been running is sent with each event generated.
1070 This allows the event handler to determine the current iteration of a looping animation
1071 or the current position of an alternating animation.
1072 This time does not include any time the animation was in the ''paused'' play state.
1075 <h3 id='AnimationEvent-interface'>
1076 Interface <code>AnimationEvent</code>
1078 <p>
1079 The <dfn>AnimationEvent</dfn> interface provides specific contextual information associated with Animation events.
1082 <h4 id='AnimationEvent-IDL'>
1083 IDL Definition</h4>
1085 <pre class='idl'>
1086 [Constructor(DOMString <var title="">type</var>, optional <i>AnimationEventInit</i> <var title="">animationEventInitDict</var>)]
1087 interface AnimationEvent : <a class="external" href="http://dvcs.w3.org/hg/domcore/raw-file/tip/Overview.html#event">Event</a> {
1088 readonly attribute DOMString <a href="#AnimationEvent-animationName" title="AnimationEvent-lengthComputable">animationName</a>;
1089 readonly attribute float <a href="#AnimationEvent-elapsedTime" title="dom-ProgressEvent-loaded">elapsedTime</a>;
1090 readonly attribute DOMString <a href="#AnimationEvent-pseudoElement" title="AnimationEvent-pseudoElement">pseudoElement</a>;
1091 };
1093 dictionary <dfn id="AnimationEventInit">AnimationEventInit</dfn> : <a class="external" href="http://dvcs.w3.org/hg/domcore/raw-file/tip/Overview.html#eventinit">EventInit</a> {
1094 DOMString <span title="AnimationEventInit-animationName">animationName</span>;
1095 float <span title="AnimationEventInit-loaded">elapsedTime</span>;
1096 DOMString <span title="AnimationEventInit-pseudoElement">pseudoElement</span>;
1097 }
1099 </pre>
1102 <h4 id='AnimationEvent-attributes'>
1103 Attributes</h4>
1105 <dl>
1106 <dt><code><dfn id='AnimationEvent-animationName'>animationName</dfn></code> of type <code>DOMString</code>, readonly
1107 <dd>
1108 The value of the 'animation-name' property of the animation that fired the event.
1110 <dt><code><dfn id='AnimationEvent-elapsedTime'>elapsedTime</dfn></code> of type <code>float</code>, readonly
1111 <dd>
1112 The amount of time the animation has been running,
1113 in seconds,
1114 when this event fired,
1115 excluding any time the animation was paused.
1116 For an "animationstart" event,
1117 the elapsedTime is zero unless there was a negative value for 'animation-delay',
1118 in which case the event will be fired with an <code>elapsedTime</code> of (-1 * delay).
1120 <dt><code><dfn id='AnimationEvent-pseudoElement'>pseudoElement</dfn></code> of type <code>DOMString</code>, readonly
1121 <dd>
1122 The name (beginning with two colons) of the CSS pseudo-element on
1123 which the animation runs (in which case the target of the event
1124 is that pseudo-element's corresponding element), or the empty string
1125 if the animation runs on an element (which means the target of the event
1126 is that element).
1127 </dl>
1129 <p>
1130 <code id="AnimationEvent-constructor">AnimationEvent(type, animationEventInitDict)</code>
1131 is an <a class="external" href="http://dvcs.w3.org/hg/domcore/raw-file/tip/Overview.html#concept-event-constructor">event constructor</a>.
1133 <h3 id='AnimationEvent-types'>
1134 Types of <code>AnimationEvent</code></h3>
1136 <p>
1137 The different types of Animation events that can occur are:
1139 <dl>
1140 <dt><dfn>animationstart</dfn>
1141 <dd>
1142 The <code>animationstart</code> event occurs at the start of the animation.
1143 If there is an 'animation-delay'
1144 then this event will fire once the delay period has expired.
1145 A negative delay will cause the event to fire with an <code>elapsedTime</code> equal to the absolute value of the delay.
1147 <ul>
1148 <li>Bubbles: Yes
1149 <li>Cancelable: No
1150 <li>Context Info: animationName, pseudoElement
1151 </ul>
1153 <dt><dfn>animationend</dfn>
1154 <dd>
1155 The <code>animationend</code> event occurs when the animation finishes.
1157 <ul>
1158 <li>Bubbles: Yes
1159 <li>Cancelable: No
1160 <li>Context Info: animationName, elapsedTime, pseudoElement
1161 </ul>
1163 <dt><dfn>animationiteration</dfn>
1164 <dd>
1165 The <code>animationiteration</code> event occurs at the end of each iteration of an animation,
1166 except when an <code>animationend</code> event would fire at the same time.
1167 This means that this event does not occur for animations with an iteration count of one or less.
1169 <ul>
1170 <li>Bubbles: Yes
1171 <li>Cancelable: No
1172 <li>Context Info: animationName, elapsedTime, pseudoElement
1173 </ul>
1174 </dl>
1177 <h2 id="dom-interfaces">
1178 DOM Interfaces</h2>
1180 <p>
1181 CSS animation is exposed to the CSSOM through a pair of new interfaces describing the keyframes.
1184 <h3 id='CSSRule-interface'>
1185 Interface <code>CSSRule</code></h3>
1187 <p>
1188 The following 2 rule types are added to the <dfn>CSSRule</dfn> interface.
1189 They provide identification for the new keyframe and keyframes rules.
1192 <h4 id='CSSRule-IDL'>
1193 IDL Definition</h4>
1195 <pre class='idl'>
1196 interface CSSRule {
1197 ...
1198 const unsigned short KEYFRAMES_RULE = 7;
1199 const unsigned short KEYFRAME_RULE = 8;
1200 ...
1201 };</pre>
1204 <h3 id='CSSKeyframeRule-interface'>
1205 Interface <code>CSSKeyframeRule</code></3h>
1206 <p>
1207 The <dfn>CSSKeyframeRule</dfn> interface represents the style rule for a single key.
1210 <h4 id='CSSKeyframeRule-IDL'>
1211 IDL Definition</h4>
1213 <pre class='idl'>
1214 interface CSSKeyframeRule : CSSRule {
1215 attribute DOMString keyText;
1216 readonly attribute CSSStyleDeclaration style;
1217 };</pre>
1220 <h4 id='CSSKeyframeRule-attributes'>
1221 Attributes</h4>
1223 <dl>
1224 <dt><code><dfn id='CSSKeyframeRule-keyText'>keyText</dfn></code> of type <code>DOMString</code>
1225 <dd>
1226 This attribute represents the keyframe selector as a comma-separated
1227 list of percentage values. The ''from'' and ''to'' keywords map to
1228 ''0%'' and ''100%'', respectively.
1230 <dt><code><dfn id='CSSKeyframeRule-style'>style</dfn></code> of type <code>CSSStyleDeclaration</code>
1231 <dd>
1232 This attribute represents the style associated with this keyframe.
1233 </dl>
1236 <h3 id='CSSKeyframesRule-interface'>
1237 Interface <code>CSSKeyframesRule</code></h3>
1239 <p>
1240 The <dfn>CSSKeyframesRule</dfn> interface represents a complete set of keyframes for a single animation.
1243 <h4 id='CSSKeyframesRule-IDL'>
1244 IDL Definition</h4>
1246 <pre class='idl'>
1247 interface CSSKeyframesRule : CSSRule {
1248 attribute DOMString name;
1249 readonly attribute CSSRuleList cssRules;
1251 void appendRule(in DOMString rule);
1252 void deleteRule(in DOMString key);
1253 CSSKeyframeRule findRule(in DOMString key);
1254 };</pre>
1257 <h4 id='CSSKeyframesRule-attributes'>
1258 Attributes</h4>
1260 <dl>
1261 <dt><code><dfn id='CSSKeyframesRule-name'>name</dfn></code> of type <code>DOMString</code>
1262 <dd>
1263 This attribute is the name of the keyframes, used by the 'animation-name' property.<br>
1265 <dt><code><dfn id='CSSKeyframesRules-cssRules'>cssRules</dfn></code> of type <code>CSSRuleList</code>
1266 <dd>
1267 This attribute gives access to the keyframes in the list.
1270 <h4 id='CSSKeyframesRule-appendRule'>
1271 The <code>appendRule</code> method</h4>
1273 <p>
1274 The <dfn>appendRule</dfn> method appends the passed CSSKeyframeRule into the list at the passed key.
1276 <p>
1277 Parameters:
1279 <dl>
1280 <dt><code>rule</code> of type <code>DOMString</code>
1282 <dd>
1283 The rule to be appended,
1284 expressed in the same syntax as one entry in the ''@keyframes'' rule.
1285 </dl>
1287 <p>
1288 No Return Value
1290 <p>
1291 No Exceptions
1294 <h4 id='CSSKeyframesRules-deleteRule'>
1295 The <code>deleteRule</code> method</h4>
1297 <p>
1298 The <dfn>deleteRule</dfn> method deletes the CSSKeyframeRule with the passed key.
1299 If a rule with this key does not exist,
1300 the method does nothing.
1302 <p>
1303 Parameters:
1305 <dl>
1306 <dt><code>key</code> of type <code>DOMString</code>
1307 <dd>
1308 The key which describes the rule to be deleted.
1309 The key must resolve to a number between 0 and 1,
1310 or the rule is ignored.
1311 </dl>
1313 <p>
1314 No Return Value
1316 <p>
1317 No Exceptions
1320 <h4 id='CSSKeyframesRule-findRule'>
1321 The <code>findRule</code> method</h4>
1323 <p>
1324 The <code>findRule</code> method returns the rule with a key matching the passed key.
1325 If no such rule exists,
1326 a null value is returned.
1328 <p>
1329 Parameters:
1331 <dl>
1332 <dt><code>key</code> of type <code>DOMString</code>
1333 <dd>
1334 The key which described the rule to find.
1335 The key must resolve to a number between 0 and 1,
1336 or the rule is ignored.
1337 </dl>
1339 <p>
1340 Return Value:
1342 <dl>
1343 <dt><code>CSSKeyframeRule</code>
1344 <dd>
1345 The found rule.
1346 </dl>
1348 <p>
1349 No Exceptions
1352 <h2 id="acknowledgments">Acknowledgments</h2>
1354 <p>Thanks especially to the feedback from
1355 Tab Atkins,
1356 Carine Bournez,
1357 Estelle Weyl,
1358 and all the rest of the
1359 <a href="http://lists.w3.org/Archives/Public/www-style/">www-style</a> community.
1361 <h2>References</h2>
1363 <h3 class="no-num">Normative references</h3>
1364 <!--normative-->
1366 <h3 class="no-num">Other references</h3>
1367 <!--informative-->
1371 <h2 class="no-num">Property index</h2>
1372 <!-- properties -->
1376 <h2 class="no-num" id="index">Index</h2>
1377 <!--index-->
1379 </body>
1380 </html>
1381 <!-- Keep this comment at the end of the file
1382 Local variables:
1383 mode: sgml
1384 sgml-declaration:"~/SGML/HTML4.decl"
1385 sgml-default-doctype-name:"html"
1386 sgml-minimize-attributes:t
1387 sgml-nofill-elements:("pre" "style" "br")
1388 sgml-live-element-indicator:t
1389 sgml-omittag:nil
1390 sgml-shorttag:nil
1391 sgml-namecase-general:t
1392 sgml-general-insert-case:lower
1393 sgml-always-quote-attributes:t
1394 sgml-indent-step:nil
1395 sgml-indent-data:t
1396 sgml-parent-document:nil
1397 sgml-exposed-tags:nil
1398 sgml-local-catalogs:nil
1399 sgml-local-ecat-files:nil
1400 End:
1401 -->
