css3-animations/Overview.src.html@2ccb60ab6e99
css3-animations/Overview.src.html
Wed, 20 Feb 2013 12:17:11 -0800
- author
- L. David Baron <dbaron@dbaron.org>
- date
- Wed, 20 Feb 2013 12:17:11 -0800
- changeset 7504
- 2ccb60ab6e99
- parent 7459
- 8c3f1f081e76
- child 7517
- 5e26a796fb84
- permissions
- -rw-r--r--
[css3-animations] Update Previous Version link post-publication, and a few other ease-of-publication tweaks.
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-[STATUS].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]">[VERSION]</a>
24 <dt>Latest version:
25 <dd><a
26 href="http://www.w3.org/TR/css3-animations/">[LATEST]</a>
27 <dt>Editor's draft:
28 <dd><a href="http://dev.w3.org/csswg/[SHORTNAME]/">http://dev.w3.org/csswg/[SHORTNAME]/</a>
29 (<a href="https://dvcs.w3.org/hg/csswg/log/tip/[SHORTNAME]/Overview.src.html">change log</a>)
30 <dt>Previous version:
31 <dd><a href="http://www.w3.org/TR/2012/WD-css3-animations-20130219/">
32 http://www.w3.org/TR/2012/WD-css3-animations-20130219/</a>
33 <dt id="editors-list">Editors:
34 <dd><a href="mailto:dino@apple.com">Dean Jackson</a> (<a
35 href="http://www.apple.com/">Apple Inc</a>)
36 <dd><a href="mailto:hyatt@apple.com">David Hyatt</a> (<a
37 href="http://www.apple.com/">Apple Inc</a>)
38 <dd><a href="mailto:cmarrin@apple.com">Chris Marrin</a> (<a
39 href="http://www.apple.com/">Apple Inc</a>)
40 <dd><a href="mailto:sylvaing@microsoft.com">Sylvain Galineau</a>
41 (<a class=org href="http://www.microsoft.com/">Microsoft</a>)
42 <dd class=vcard><a class=fn href="http://dbaron.org/">L. David Baron</a>
43 (<a class=org href="http://www.mozilla.org/">Mozilla</a>)
45 <dt>Issues list:
46 <dd><a href="https://www.w3.org/Bugs/Public/buglist.cgi?query_format=advanced&product=CSS&component=Animations&resolution=---&cmdtype=doit">in Bugzilla</a>
48 <dt>Discussion:
49 <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>”
51 <dt>Test suite:
52 <dd>none yet
53 </dl>
55 <!--copyright-->
57 <hr title="Separator for header">
58 </div>
60 <h2 class="no-num no-toc" id="abstract">
61 Abstract</h2>
63 <p>
64 This CSS module describes a way for authors to animate the values of CSS properties over time,
65 using keyframes.
66 The behavior of these keyframe animations can be controlled by specifying their duration,
67 number of repeats,
68 and repeating behavior.
71 <h2 class="no-num no-toc" id="status">
72 Status of this document</h2>
73 <!--status-->
76 <h2 class="no-num no-toc" id="contents">
77 Table of contents</h2>
78 <!--toc-->
81 <h2 id="introduction">
82 Introduction</h2>
84 <p><em>This section is not normative.</em>
86 <p>
87 CSS Transitions [[CSS3-TRANSITIONS]]
88 provide a way to interpolate CSS property values
89 when they change as a result of underlying property changes.
90 This provides an easy way to do simple animation,
91 but the start and end states of the animation are controlled by the existing property values,
92 and transitions provide little control to the author on how the animation progresses.
94 <p>
95 This proposal introduces <dfn>defined animations</dfn>,
96 in which the author can specify the changes in CSS properties over time as a set of keyframes.
97 Animations are similar to transitions
98 in that they change the presentational value of CSS properties over time.
99 The principal difference is that
100 while transitions trigger <em>implicitly</em> when property values change,
101 animations are <em>explicitly</em> executed when the animation properties are applied.
102 Because of this,
103 animations require explicit values for the properties being animated.
104 These values are specified using animation keyframes, described below.
106 <p>
107 Many aspects of the animation can be controlled,
108 including how many times the animation iterates,
109 whether or not it alternates between the begin and end values,
110 and whether or not the animation should be running or paused.
111 An animation can also delay its start time.
113 <h2 id="values">
114 Values</h2>
116 <p>
117 This specification follows the <a href="http://www.w3.org/TR/CSS21/about.html#property-defs">CSS property definition conventions</a> from [[!CSS21]].
118 Value types not defined in this specification are defined in CSS Level 2 Revision 1 [[!CSS21]].
119 Other CSS modules may expand the definitions of these value types:
120 for example [[CSS3VAL]], when combined with this module,
121 expands the definition of the <var><length></var> value type as used in this specification.
123 <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.
126 <h2 id="animations">
127 Animations</h2>
129 <p>
130 CSS Animations affect computed property values.
131 During the execution of an animation,
132 the computed value for a property is controlled by the animation.
133 This overrides the value specified in the normal styling system.
134 Animations override all normal rules, but are overriden by
135 !important rules.
137 <p>
138 If at one point in time there are multiple animations specifying behavior for the same property,
139 the animation whose name occurs last in the value of 'animation-name'
140 will override the other animations at that point.
143 <p>
144 An animation does not affect the computed value before the application of the animation,
145 before the animation delay has expired,
146 and after the end of the animation.
149 <div class="figure">
150 <img src="sandwich.png" alt="">
152 <p class="caption">
153 Computation of animated property values
154 </div>
156 <p>
157 The diagram above shows how property values are computed.
158 The intrinsic style is shown at the top of the diagram.
159 The computed value is derived from intrinsic style
160 at the times when an animation is not running
161 and also when an animation is delayed
162 (see below for specification of animation delay).
163 During an animation,
164 the computed style is derived from the animated value.
167 <p>
168 The start time of an animation is the latter of two moments:
169 the time at which the style is resolved that specifies the animation,
170 or the time the document's load event is fired.
171 Therefore, an animation specified in the document style sheet
172 will begin at the document load.
173 An animation specified on an element by modifying the style after the document has loaded
174 will start when the style is resolved.
175 That may be immediately in the case of a pseudo style rule such as hover,
176 or may be when the scripting engine returns control to the browser
177 (in the case of style applied by script).
180 <p>
181 An animation applies to an element
182 if the element has a value for 'animation-name' that references a valid keyframes rule.
183 Once an animation has started
184 it continues until it ends
185 or the 'animation-name' is removed.
186 The values used for the keyframes and animation properties are snapshotted at the time the animation starts.
187 Changing them during the execution of the animation has no effect.
188 Note also that changing the value of 'animation-name' does not necessarily restart an animation
189 (e.g., if a list of animations are applied and one is removed from the list,
190 only that animation will stop;
191 The other animations will continue).
192 In order to restart an animation,
193 it must be removed then reapplied.
196 <p>
197 The end of the animation is defined by the combination of the
198 'animation-duration',
199 'animation-iteration-count' and
200 'animation-fill-mode' properties.
203 <div class="example">
204 <pre>
205 div {
206 animation-name: diagonal-slide;
207 animation-duration: 5s;
208 animation-iteration-count: 10;
209 }
211 @keyframes diagonal-slide {
213 from {
214 left: 0;
215 top: 0;
216 }
218 to {
219 left: 100px;
220 top: 100px;
221 }
223 }</pre>
225 <p>
226 This will produce an animation
227 that moves an element from (0, 0) to (100px, 100px)
228 over five seconds
229 and repeats itself nine times
230 (for a total of ten iterations).
231 </div>
233 <p>
234 Setting the display property to 'none' will terminate any running animation
235 applied to the element and its descendants.
237 If an element has a display of 'none', updating display to a value other than 'none'
238 will start all animations applied to the element by the 'animation-name' property,
239 as well as all animations applied to descendants with display other than 'none'.
240 </p>
242 <p>
243 While authors can use animations to create dynamically changing content,
244 dynamically changing content can lead to seizures in some users.
245 For information on how to avoid content that can lead to seizures, see
246 <a href="http://www.w3.org/TR/WCAG20/#seizure">Guideline 2.3:
247 Seizures:
248 Do not design content in a way that is known to cause seizures</a>
249 ([[WCAG20]]).
250 </p>
252 <h2 id="keyframes">
253 Keyframes</h2>
254 <p>
255 Keyframes are used to specify the values for the animating properties
256 at various points during the animation.
257 The keyframes specify the behavior of one cycle of the animation;
258 the animation may iterate one or more times.
260 <p>
261 Keyframes are specified using a specialized CSS at-rule.
262 A @keyframes rule consists of the keyword "@keyframes",
263 followed by an identifier giving a name for the animation
264 (which will be referenced using 'animation-name'),
265 followed by a set of style rules
266 (delimited by curly braces).
268 <p>
269 The <dfn>keyframe selector</dfn> for a keyframe style rule
270 consists of a comma-separated list of percentage values
271 or the keywords 'from' or 'to'.
272 The selector is used to specify the percentage along the duration of the animation that the keyframe represents.
273 The keyframe itself is specified by the block of property values declared on the selector.
274 The keyword 'from' is equivalent to the value ''0%''.
275 The keyword 'to' is equivalent to the value ''100%''.
276 <span class='note'>Note that the percentage unit specifier must be used on percentage values.
277 Therefore, ''0'' is an invalid keyframe selector.</span>
279 <p>
280 If a ''0%'' or ''from'' keyframe is not specified,
281 then the user agent constructs a ''0%'' keyframe
282 using the computed values of the properties being animated.
283 If a ''100%'' or ''to'' keyframe is not specified,
284 then the user agent constructs a ''100%'' keyframe
285 using the computed values of the properties being animated.
286 If a keyframe selector specifies
287 negative percentage values or
288 values higher than 100%,
289 then the keyframe will be ignored.
291 <p>
292 The <dfn>keyframe declaration block</dfn> for a keyframe rule
293 consists of properties and values.
294 Properties that are unable to be animated are ignored in these rules,
295 with the exception of 'animation-timing-function',
296 the behavior of which is described below. In addition, keyframe rule declarations qualified with !important are ignored.
298 <p class="issue">
299 Need to describe what happens if a property is not present in all keyframes.
301 <p>
302 The @keyframes rule that is used by an animation
303 will be the last one encountered in sorted rules order
304 that matches the name of the animation specified by the 'animation-name' property.
305 @keyframes rules do not cascade;
306 therefore, an animation will never derive keyframes from more than one @keyframes rule.
308 <p class='note'>
309 Note that since empty @keyframes rule are valid, they may hide the keyframes of
310 those preceding animation definitions with a matching name.
312 <p>
313 To determine the set of keyframes,
314 all of the values in the selectors are sorted in increasing order by time.
315 If there are any duplicates,
316 then the last keyframe specified inside the @keyframes rule
317 will be used to provide the keyframe information for that time.
318 There is no cascading within a @keyframes rule if multiple keyframes specify the same keyframe selector values.
320 <p>
321 If a property is not specified for a keyframe,
322 or is specified but invalid,
323 the animation of that property proceeds as if that keyframe did not exist.
324 Conceptually,
325 it is as if a set of keyframes is constructed for each property that is present in any of the keyframes,
326 and an animation is run independently for each property.
328 <div class="example">
329 <pre>
330 @keyframes wobble {
331 0% {
332 left: 100px;
333 }
335 40% {
336 left: 150px;
337 }
339 60% {
340 left: 75px;
341 }
343 100% {
344 left: 100px;
345 }
346 }</pre>
348 <p>
349 Four keyframes are specified for the animation named "wobble".
350 In the first keyframe,
351 shown at the beginning of the animation cycle,
352 the value of the 'left' property being animated is ''100px''.
353 By 40% of the animation duration,
354 'left' has animated to ''150px''.
355 At 60% of the animation duration,
356 'left' has animated back to ''75px''.
357 At the end of the animation cycle,
358 the value of 'left' has returned to ''100px''.
359 The diagram below shows the state of the animation if it were given a duration of ''10s''.
361 <div class="figure">
362 <img src="animation1.png" alt="">
364 <p class="caption">
365 Animations states specified by keyframes
366 </div>
367 </div>
369 <p>
370 The following is the grammar for the keyframes rule.
372 <pre>
373 keyframes_rule: KEYFRAMES_SYM S+ IDENT S* '{' S* keyframes_blocks '}' S*;
375 keyframes_blocks: [ keyframe_selector '{' S* declaration? [ ';' S* declaration? ]* '}' S* ]* ;
377 keyframe_selector: [ FROM_SYM | TO_SYM | PERCENTAGE ] S* [ ',' S* [ FROM_SYM | TO_SYM | PERCENTAGE ] S* ]*;
379 @{K}{E}{Y}{F}{R}{A}{M}{E}{S} {return KEYFRAMES_SYM;}
380 {F}{R}{O}{M} {return FROM_SYM;}
381 {T}{O} {return TO_SYM;}</pre>
384 <h3 id="timing-functions">
385 Timing functions for keyframes</h3>
387 <p>
388 A keyframe style rule may also declare the timing function that is to be used
389 as the animation moves to the next keyframe.
391 <div class="example">
392 <pre>
393 @keyframes bounce {
395 from {
396 top: 100px;
397 animation-timing-function: ease-out;
398 }
400 25% {
401 top: 50px;
402 animation-timing-function: ease-in;
403 }
405 50% {
406 top: 100px;
407 animation-timing-function: ease-out;
408 }
410 75% {
411 top: 75px;
412 animation-timing-function: ease-in;
413 }
415 to {
416 top: 100px;
417 }
419 }</pre>
421 <p>
422 Five keyframes are specified for the animation named "bounce".
423 Between the first and second keyframe
424 (i.e., between 0% and 25%)
425 an ''ease-out'' timing function is used.
426 Between the second and third keyframe
427 (i.e., between 25% and 50%)
428 an ''ease-in'' timing function is used.
429 And so on.
430 The effect will appear as an element that moves up the page ''50px'',
431 slowing down as it reaches its highest point
432 then speeding up as it falls back to ''100px''.
433 The second half of the animation behaves in a similar manner,
434 but only moves the element ''25px'' up the page.
435 </div>
437 <p>
438 A timing function specified on the "to" or 100% keyframe is ignored.
440 <p>
441 See the 'animation-timing-function' property for more information.
444 <h3 id="animation-name-property">
445 The 'animation-name' Property</h3>
447 <p>
448 The 'animation-name' property defines a list of animations that apply.
449 Each name is used to select the keyframe at-rule
450 that provides the property values for the animation.
451 If the name does not match any keyframe at-rule,
452 there are no properties to be animated
453 and the animation will not execute.
454 Furthermore,
455 if the animation name is ''none''
456 then there will be no animation.
457 This can be used to override any animations coming from the cascade.
458 If multiple animations are attempting to modify the same property,
459 then the animation closest to the end of the list of names wins.
461 <p id="list-matching">
462 Each animation listed by name
463 should have a corresponding value for the other animation properties listed below.
464 If the lists of values for the other animation properties do not have the same length,
465 the length of the 'animation-name' list
466 determines the number of items in each list examined when starting animations.
467 The lists are matched up from the first value:
468 excess values at the end are not used.
469 If one of the other properties doesn't have enough comma-separated values to match the number of values of 'animation-name',
470 the UA must calculate its used value by repeating the list of values until there are enough.
471 This truncation or repetition does not affect the computed value.
472 <span class="note">Note: This is analogous to the behavior of the 'background-*'properties,
473 with 'background-image' analogous to 'animation-name'.</span>
476 <table class=propdef>
477 <tr>
478 <th>Name:</th>
479 <td><dfn>animation-name</dfn>
480 <tr>
481 <th><a href="#values">Value</a>:
482 <td><span><single-animation-name></span> [ ',' <span><single-animation-name></span> ]*
483 <tr>
484 <th>Initial:
485 <td>''none''
486 <tr>
487 <th>Applies To:
488 <td>all elements, ::before and ::after pseudo-elements
489 <tr>
490 <th>Inherited:
491 <td>no
492 <tr>
493 <th>Animatable:
494 <td>no
495 <tr>
496 <th>Percentages:
497 <td>N/A
498 <tr>
499 <th>Media:
500 <td>visual
501 <tr>
502 <th>Computed Value:
503 <td>As specified
504 <tr>
505 <th>Canonical Order:
506 <td><abbr title="follows order of property value definition">per grammar</abbr>
507 </table>
509 <div class="prod">
510 <dfn id="single-animation-name"><single-animation-name></dfn> = none | <IDENT>
511 </div>
513 <!--
514 <p>
515 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.
517 <div class="example">
518 <p style="display:none">
519 Example(s):
521 <pre>
522 @keyframes 'border-bloat' {
523 from {
524 border-width: 0;
525 }
526 to {
527 border-width: 10px;
528 }
529 }
531 @keyframes 'border-diet' {
532 from {
533 border-width: 4px;
534 }
535 to {
536 border-width: 2px;
537 }
538 }
540 div {
541 animation-name: 'border-bloat', 'border-diet';
542 animation-duration: 10s, 4s;
543 }
544 </pre>
545 <p>
546 The above example has two animations executing on the same property, 'border-width'. The animations are additive. That is, the
547 resulting value for the property will be the addition of the values from the
548 two animations.
550 <p>
551 At time '0s' the element's border will be 4px wide (0px from 'border-bloat' plus 4px from 'border-diet').
552 At time '4s' the element's border will be 6px wide (4px from 'border-bloat' plus 2px from 'border-diet').
553 At time '10s' the element's border will be 10px wide (10px from 'border-bloat' and no addition from
554 'border-diet' as it is no longer executing).
556 </div>
557 -->
560 <h3 id="animation-duration-property">
561 The 'animation-duration' Property</h3>
563 <p>
564 The 'animation-duration' property defines the length of time that an animation takes to complete one cycle.
567 <table class=propdef>
568 <tr>
569 <th>Name:</th>
570 <td><dfn>animation-duration</dfn>
571 <tr>
572 <th><a href="#values">Value</a>:
573 <td> <span><time></span> [, <span><time></span>]*
574 <tr>
575 <th>Initial:
576 <td>''0s''
577 <tr>
578 <th>Applies To:
579 <td>all elements, ::before and ::after pseudo-elements
580 <tr>
581 <th>Inherited:
582 <td>no
583 <tr>
584 <th>Animatable:
585 <td>no
586 <tr>
587 <th>Percentages:
588 <td>N/A
589 <tr>
590 <th>Media:
591 <td>visual
592 <tr>
593 <th>Computed Value:
594 <td>as specified
595 <tr>
596 <th>Canonical Order:
597 <td><abbr title="follows order of property value definition">per grammar</abbr>
598 </table>
600 <p>
601 The initial value is ''0s'',
602 meaning that the animation takes no time.
603 When the duration is ''0s'' 'animation-fill-mode' still applies,
604 so an animation that fills backwards
605 will show the value of the 0% keyframe during any delay period,
606 and an animation that fills forwards will retain the value specified at the 100% keyframe,
607 even if the animation was instantaneous.
608 Also, animation events are still fired.
609 A negative 'animation-duration' value renders the declaration invalid.
612 <h3 id="animation-timing-function-property">
613 The 'animation-timing-function' Property</h3>
615 <p>
616 The 'animation-timing-function' property describes how the animation will progress over one cycle of its duration.
617 See the 'transition-timing-function' property [[!CSS3-TRANSITIONS]] for a complete description of timing function calculation.
619 <table class=propdef>
620 <tr>
621 <th>Name:</th>
622 <td><dfn>animation-timing-function</dfn>
623 <tr>
624 <th><a href="#values">Value</a>:
625 <td><span><single-timing-function></span> [ ',' <span><single-timing-function></span> ]*
626 <tr>
627 <th>Initial:
628 <td>''ease''
629 <tr>
630 <th>Applies To:
631 <td>all elements, ::before and ::after pseudo-elements
632 <tr>
633 <th>Inherited:
634 <td>no
635 <tr>
636 <th>Animatable:
637 <td>no
638 <tr>
639 <th>Percentages:
640 <td>N/A
641 <tr>
642 <th>Media:
643 <td>visual
644 <tr>
645 <th>Computed Value:
646 <td>as specified
647 <tr>
648 <th>Canonical Order:
649 <td><abbr title="follows order of property value definition">per grammar</abbr>
650 </table>
652 <p>All the valid values of ''<single-timing-function>'' are defined by the 'transition-timing-function' property [[!CSS3-TRANSITIONS]].</p>
654 <p>
655 For a keyframed animation,
656 the 'animation-timing-function' applies between keyframes,
657 not over the entire animation.
658 For example,
659 in the case of an ''ease-in-out'' timing function,
660 an animation will ease in at the start of the keyframe
661 and ease out at the end of the keyframe.
662 An 'animation-timing-function' defined within a keyframe block applies to that keyframe,
663 otherwise the timing function specified for the animation is used.
666 <h3 id="animation-iteration-count-property">
667 The 'animation-iteration-count' Property</h3>
669 <p>
670 The 'animation-iteration-count' property specifies the number of times an animation cycle is played.
671 The initial value is ''1'',
672 meaning the animation will play from beginning to end once.
673 A value of ''infinite'' will cause the animation to repeat forever.
674 Non-integer numbers will cause the animation to end part-way through a cycle.
675 Negative values of 'animation-iteration-count' are invalid.
676 This property is often used in conjunction an 'animation-direction' value of ''alternate'',
677 which will cause the animation to play in reverse on alternate cycles.
679 <table class=propdef>
680 <tr>
681 <th>Name:</th>
682 <td><dfn>animation-iteration-count</dfn>
683 <tr>
684 <th><a href="#values">Value</a>:
685 <td><span><single-animation-iteration-count></span> [ ',' <span><single-animation-iteration-count></span> ]*
686 <tr>
687 <th>Initial:
688 <td>''1''
689 <tr>
690 <th>Applies To:
691 <td>all elements, ::before and ::after pseudo-elements
692 <tr>
693 <th>Inherited:
694 <td>no
695 <tr>
696 <th>Animatable:
697 <td>no
698 <tr>
699 <th>Percentages:
700 <td>N/A
701 <tr>
702 <th>Media:
703 <td>visual
704 <tr>
705 <th>Computed Value:
706 <td>as specified
707 <tr>
708 <th>Canonical Order:
709 <td><abbr title="follows order of property value definition">per grammar</abbr>
710 </table>
712 <div class="prod">
713 <dfn id="single-animation-iteration-count"><single-animation-iteration-count></dfn> =
714 infinite | <number>
715 </div>
717 <h3 id="animation-direction-property">
718 The 'animation-direction' Property</h3>
720 <p>
721 The 'animation-direction' property defines whether or not the animation should play in reverse on some or all cycles.
722 When an animation is played in reverse the timing functions are also reversed.
723 For example, when played in reverse an ease-in animation would appear to be an ease-out animation.
725 <table class=propdef>
726 <tr>
727 <th>Name:</th>
728 <td><dfn>animation-direction</dfn>
729 <tr>
730 <th><a href="#values">Value</a>:
731 <td><span><single-animation-direction></span> [ ',' <span><single-animation-direction></span> ]*
732 <tr>
733 <th>Initial:
734 <td>''normal''
735 <tr>
736 <th>Applies To:
737 <td>all elements, ::before and ::after pseudo-elements
738 <tr>
739 <th>Inherited:
740 <td>no
741 <tr>
742 <th>Animatable:
743 <td>no
744 <tr>
745 <th>Percentages:
746 <td>N/A
747 <tr>
748 <th>Media:
749 <td>visual
750 <tr>
751 <th>Computed Value:
752 <td>as specified
753 <tr>
754 <th>Canonical Order:
755 <td><abbr title="follows order of property value definition">per grammar</abbr>
756 </table>
758 <div class="prod">
759 <dfn id="single-animation-direction"><single-animation-direction></dfn> =
760 normal | reverse | alternate | alternate-reverse
761 </div>
763 <dl>
764 <dt><dfn>normal</dfn>
765 <dd>
766 All iterations of the animation are played as specified.
768 <dt><dfn>reverse</dfn>
769 <dd>
770 All iterations of the animation are played in the reverse direction from the way they were specified.
772 <dt><dfn>alternate</dfn>
773 <dd>
774 The animation cycle iterations that are odd counts are played in the normal direction,
775 and the animation cycle iterations that are even counts are played in a reverse direction.
777 <dt><dfn>alternate-reverse</dfn>
778 <dd>
779 The animation cycle iterations that are odd counts are played in the reverse direction,
780 and the animation cycle iterations that are even counts are played in a normal direction.
781 </dl>
783 <p class='note'>
784 Note that for the purpose of determining whether an iteration is even or odd,
785 iterations start counting from 1.
788 <h3 id="animation-play-state-property">
789 The 'animation-play-state' Property</h3>
791 <p>
792 The 'animation-play-state' property defines whether the animation is running or paused.
793 A running animation can be paused by setting this property to ''paused''.
794 To continue running a paused animation this property can be set to ''running''.
795 A paused animation will continue to display the current value of the animation in a static state,
796 as if the time of the animation is constant.
797 When a paused animation is resumed,
798 it restarts from the current value,
799 not necessarily from the beginning of the animation.
801 <table class=propdef>
802 <tr>
803 <th>Name:</th>
804 <td><dfn>animation-play-state</dfn>
805 <tr>
806 <th><a href="#values">Value</a>:
807 <td><span><single-animation-play-state></span> [ ',' <span><single-animation-play-state></span> ]*
808 <tr>
809 <th>Initial:
810 <td>''running''
811 <tr>
812 <th>Applies To:
813 <td>all elements, ::before and ::after pseudo-elements
814 <tr>
815 <th>Inherited:
816 <td>no
817 <tr>
818 <th>Animatable:
819 <td>no
820 <tr>
821 <th>Percentages:
822 <td>N/A
823 <tr>
824 <th>Media:
825 <td>visual
826 <tr>
827 <th>Computed Value:
828 <td>as specified
829 <tr>
830 <th>Canonical Order:
831 <td><abbr title="follows order of property value definition">per grammar</abbr>
832 </table>
834 <div class="prod">
835 <dfn id="single-animation-play-state"><single-animation-play-state></dfn> =
836 running | paused
837 </div>
839 <h3 id="animation-delay-property">
840 The 'animation-delay' Property</h3>
842 <p>
843 The 'animation-delay' property defines when the animation will start.
844 It allows an animation to begin execution some time after it is applied.
845 An 'animation-delay' value of ''0s'' means the animation will execute as soon as it is applied.
846 Otherwise, the value specifies an offset from the moment the animation is applied,
847 and the animation will delay execution by that offset.
849 <p>
850 If the value for 'animation-delay' is a negative time offset
851 then the animation will execute the moment it is applied,
852 but will appear to have begun execution at the specified offset.
853 That is, the animation will appear to begin part-way through its play cycle.
854 In the case where an animation has implied starting values and a negative 'animation-delay',
855 the starting values are taken from the moment the animation is applied.
857 <table class=propdef>
858 <tr>
859 <th>Name:</th>
860 <td><dfn>animation-delay</dfn>
861 <tr>
862 <th><a href="#values">Value</a>:
863 <td> <span><time></span> [, <span><time></span>]*
864 <tr>
865 <th>Initial:
866 <td>''0s''
867 <tr>
868 <th>Applies To:
869 <td>all elements, ::before and ::after pseudo-elements
870 <tr>
871 <th>Inherited:
872 <td>no
873 <tr>
874 <th>Animatable:
875 <td>no
876 <tr>
877 <th>Percentages:
878 <td>N/A
879 <tr>
880 <th>Media:
881 <td>visual
882 <tr>
883 <th>Computed Value:
884 <td>as specified
885 <tr>
886 <th>Canonical Order:
887 <td><abbr title="follows order of property value definition">per grammar</abbr>
888 </table>
891 <h3 id="animation-fill-mode-property">
892 The 'animation-fill-mode' Property</h3>
894 <p>
895 The 'animation-fill-mode' property defines what values are applied by the animation outside the time it is executing.
896 By default, an animation will not affect property values
897 between the time it is applied
898 (the 'animation-name' property is set on an element)
899 and the time it begins execution
900 (which is determined by the 'animation-delay' property).
901 Also, by default an animation does not affect property values after the animation ends
902 (determined by the 'animation-duration' property).
903 The 'animation-fill-mode' property can override this behavior.
905 <p>
906 If the value for 'animation-fill-mode' is ''backwards'',
907 then the animation will apply
908 the property values defined in the keyframe
909 that will start the first iteration of the animation,
910 during the period defined by 'animation-delay'.
911 These are either the values of the ''from'' keyframe
912 (when 'animation-direction' is ''normal'' or ''alternate'')
913 or those of the ''to'' keyframe
914 (when 'animation-direction' is ''reverse'' or ''alternate-reverse'').
916 <p>
917 If the value for 'animation-fill-mode' is ''forwards'',
918 then after the animation ends
919 (as determined by its 'animation-iteration-count'),
920 the animation will apply
921 the property values for the time the animation ended.
922 When 'animation-iteration-count' is an integer greater than zero,
923 the values applied will be
924 those for the end of the last completed iteration of the animation
925 (rather than the values for
926 the start of the iteration that would be next).
927 When 'animation-iteration-count' is zero,
928 the values applied will be those that would start the first iteration
929 (just as when 'animation-fill-mode' is ''backwards'').
931 <p>
932 If the value for 'animation-fill-mode' is ''both'',
933 then the animation will follow the rules for both 'forwards' and 'backwards'.
934 That is, it will extend the animation properties in both directions.
936 <table class=propdef>
937 <tr>
938 <th>Name:</th>
939 <td><dfn>animation-fill-mode</dfn>
940 <tr>
941 <th><a href="#values">Value</a>:
942 <td><span><single-animation-fill-mode></span> [ ',' <span><single-animation-fill-mode></span> ]*
943 <tr>
944 <th>Initial:
945 <td>''none''
946 <tr>
947 <th>Applies To:
948 <td>all elements, ::before and ::after pseudo-elements
949 <tr>
950 <th>Inherited:
951 <td>no
952 <tr>
953 <th>Animatable:
954 <td>no
955 <tr>
956 <th>Percentages:
957 <td>N/A
958 <tr>
959 <th>Media:
960 <td>visual
961 <tr>
962 <th>Computed Value:
963 <td>as specified
964 <tr>
965 <th>Canonical Order:
966 <td><abbr title="follows order of property value definition">per grammar</abbr>
967 </table>
969 <div class="prod">
970 <dfn id="single-animation-fill-mode"><single-animation-fill-mode></dfn> =
971 none | forwards | backwards | both
972 </div>
974 <h3 id="animation-shorthand-property">
975 The 'animation' Shorthand Property</h3>
977 <p>
978 The 'animation' shorthand property is a comma-separated list of
979 animation definitions, each of which combines seven of the animation properties
980 into a single component value.
982 <table class=propdef>
983 <tr>
984 <th>Name:</th>
985 <td><dfn>animation</dfn>
986 <tr>
987 <th><a href="#values">Value</a>:
988 <td><span><single-animation></span> [ ',' <span><single-animation></span> ]*
989 <tr>
990 <th>Initial:
991 <td>see individual properties
992 <tr>
993 <th>Applies To:
994 <td>all elements, ::before and ::after pseudo-elements
995 <tr>
996 <th>Inherited:
997 <td>see individual properties
998 <tr>
999 <th>Animatable:
1000 <td>no
1001 <tr>
1002 <th>Percentages:
1003 <td>N/A
1004 <tr>
1005 <th>Media:
1006 <td>visual
1007 <tr>
1008 <th>Computed Value:
1009 <td>see individual properties
1010 <tr>
1011 <th>Canonical Order:
1012 <td><abbr title="follows order of property value definition">per grammar</abbr>
1013 </table>
1015 <div class="prod">
1016 <dfn id="single-animation"><single-animation></dfn> =
1017 <single-animation-name> ||
1018 <span><time></span> ||
1019 <single-animation-timing-function> ||
1020 <span><time></span> ||
1021 <single-animation-iteration-count> ||
1022 <single-animation-direction> ||
1023 <single-animation-fill-mode> ||
1024 <single-animation-play-state>
1025 </div>
1027 <p>
1028 Note that order is important within each animation definition:
1029 the first value that can be parsed as a <var><time></var> is assigned to the
1030 animation-duration,
1031 and the second value that can be parsed as a <var><time></var> is assigned to
1032 animation-delay.
1033 </p>
1035 <p class="issue">
1036 An alternative proposal is to accept the font shorthand approach
1037 of using a "/" character between the values of the same type.
1038 e.g. 2s/4s would mean a duration of 2 seconds and a delay of 4 seconds.
1040 <p class="issue">
1041 Need to also explain how order is important in terms of animation-name
1042 versus keywords, and probably also adjust the canonical order to
1043 match.
1045 <h2 id="animation-events">
1046 Animation Events</h2>
1048 <p>
1049 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>.
1050 The start and end of an animation,
1051 and the end of each iteration of an animation,
1052 all generate DOM events.
1053 An element can have multiple properties being animated simultaneously.
1054 This can occur either with a single 'animation-name' value
1055 with keyframes containing multiple properties,
1056 or with multiple 'animation-name' values.
1057 For the purposes of events,
1058 each 'animation-name' specifies a single animation.
1059 Therefore an event will be generated for each 'animation-name' value
1060 and not necessarily for each property being animated.
1062 <p>
1063 Any animation for which both a valid keyframe rule and a non-zero duration are
1064 defined will run and generate events; this includes animations with empty
1065 keyframe rules.
1067 <p>
1068 The time the animation has been running is sent with each event generated.
1069 This allows the event handler to determine the current iteration of a looping animation
1070 or the current position of an alternating animation.
1071 This time does not include any time the animation was in the ''paused'' play state.
1074 <h3 id='AnimationEvent-interface'>
1075 Interface <code>AnimationEvent</code></h3>
1077 <p>
1078 The <dfn>AnimationEvent</dfn> interface provides specific contextual information associated with Animation events.
1081 <h4 id='AnimationEvent-IDL'>
1082 IDL Definition</h4>
1084 <pre class='idl'>
1085 [Constructor(DOMString <var title="">type</var>, optional <i>AnimationEventInit</i> <var title="">animationEventInitDict</var>)]
1086 interface AnimationEvent : <a class="external" href="http://dvcs.w3.org/hg/domcore/raw-file/tip/Overview.html#event">Event</a> {
1087 readonly attribute DOMString <a href="#AnimationEvent-animationName" title="AnimationEvent-lengthComputable">animationName</a>;
1088 readonly attribute float <a href="#AnimationEvent-elapsedTime" title="dom-ProgressEvent-loaded">elapsedTime</a>;
1089 readonly attribute DOMString <a href="#AnimationEvent-pseudoElement" title="AnimationEvent-pseudoElement">pseudoElement</a>;
1090 };
1092 dictionary <dfn id="AnimationEventInit">AnimationEventInit</dfn> : <a class="external" href="http://dvcs.w3.org/hg/domcore/raw-file/tip/Overview.html#eventinit">EventInit</a> {
1093 DOMString <span title="AnimationEventInit-animationName">animationName</span>;
1094 float <span title="AnimationEventInit-loaded">elapsedTime</span>;
1095 DOMString <span title="AnimationEventInit-pseudoElement">pseudoElement</span>;
1096 }
1098 </pre>
1101 <h4 id='AnimationEvent-attributes'>
1102 Attributes</h4>
1104 <dl>
1105 <dt><code><dfn id='AnimationEvent-animationName'>animationName</dfn></code> of type <code>DOMString</code>, readonly
1106 <dd>
1107 The value of the 'animation-name' property of the animation that fired the event.
1109 <dt><code><dfn id='AnimationEvent-elapsedTime'>elapsedTime</dfn></code> of type <code>float</code>, readonly
1110 <dd>
1111 The amount of time the animation has been running,
1112 in seconds,
1113 when this event fired,
1114 excluding any time the animation was paused.
1115 For an "animationstart" event,
1116 the elapsedTime is zero unless there was a negative value for 'animation-delay',
1117 in which case the event will be fired with an <code>elapsedTime</code> of (-1 * delay).
1119 <dt><code><dfn id='AnimationEvent-pseudoElement'>pseudoElement</dfn></code> of type <code>DOMString</code>, readonly
1120 <dd>
1121 The name (beginning with two colons) of the CSS pseudo-element on
1122 which the animation runs (in which case the target of the event
1123 is that pseudo-element's corresponding element), or the empty string
1124 if the animation runs on an element (which means the target of the event
1125 is that element).
1126 </dl>
1128 <p>
1129 <code id="AnimationEvent-constructor">AnimationEvent(type, animationEventInitDict)</code>
1130 is an <a class="external" href="http://dvcs.w3.org/hg/domcore/raw-file/tip/Overview.html#concept-event-constructor">event constructor</a>.
1132 <h3 id='AnimationEvent-types'>
1133 Types of <code>AnimationEvent</code></h3>
1135 <p>
1136 The different types of Animation events that can occur are:
1138 <dl>
1139 <dt><dfn>animationstart</dfn>
1140 <dd>
1141 The <code>animationstart</code> event occurs at the start of the animation.
1142 If there is an 'animation-delay'
1143 then this event will fire once the delay period has expired.
1144 A negative delay will cause the event to fire with an <code>elapsedTime</code> equal to the absolute value of the delay.
1146 <ul>
1147 <li>Bubbles: Yes
1148 <li>Cancelable: No
1149 <li>Context Info: animationName, pseudoElement
1150 </ul>
1152 <dt><dfn>animationend</dfn>
1153 <dd>
1154 The <code>animationend</code> event occurs when the animation finishes.
1156 <ul>
1157 <li>Bubbles: Yes
1158 <li>Cancelable: No
1159 <li>Context Info: animationName, elapsedTime, pseudoElement
1160 </ul>
1162 <dt><dfn>animationiteration</dfn>
1163 <dd>
1164 The <code>animationiteration</code> event occurs at the end of each iteration of an animation,
1165 except when an <code>animationend</code> event would fire at the same time.
1166 This means that this event does not occur for animations with an iteration count of one or less.
1168 <ul>
1169 <li>Bubbles: Yes
1170 <li>Cancelable: No
1171 <li>Context Info: animationName, elapsedTime, pseudoElement
1172 </ul>
1173 </dl>
1176 <h2 id="dom-interfaces">
1177 DOM Interfaces</h2>
1179 <p>
1180 CSS animation is exposed to the CSSOM through a pair of new interfaces describing the keyframes.
1183 <h3 id='CSSRule-interface'>
1184 Interface <code>CSSRule</code></h3>
1186 <p>
1187 The following 2 rule types are added to the <dfn>CSSRule</dfn> interface.
1188 They provide identification for the new keyframe and keyframes rules.
1191 <h4 id='CSSRule-IDL'>
1192 IDL Definition</h4>
1194 <pre class='idl'>
1195 interface CSSRule {
1196 ...
1197 const unsigned short KEYFRAMES_RULE = 7;
1198 const unsigned short KEYFRAME_RULE = 8;
1199 ...
1200 };</pre>
1203 <h3 id='CSSKeyframeRule-interface'>
1204 Interface <code>CSSKeyframeRule</code></h3>
1205 <p>
1206 The <dfn>CSSKeyframeRule</dfn> interface represents the style rule for a single key.
1209 <h4 id='CSSKeyframeRule-IDL'>
1210 IDL Definition</h4>
1212 <pre class='idl'>
1213 interface CSSKeyframeRule : CSSRule {
1214 attribute DOMString keyText;
1215 readonly attribute CSSStyleDeclaration style;
1216 };</pre>
1219 <h4 id='CSSKeyframeRule-attributes'>
1220 Attributes</h4>
1222 <dl>
1223 <dt><code><dfn id='CSSKeyframeRule-keyText'>keyText</dfn></code> of type <code>DOMString</code>
1224 <dd>
1225 This attribute represents the keyframe selector as a comma-separated
1226 list of percentage values. The ''from'' and ''to'' keywords map to
1227 ''0%'' and ''100%'', respectively.
1229 <dt><code><dfn id='CSSKeyframeRule-style'>style</dfn></code> of type <code>CSSStyleDeclaration</code>
1230 <dd>
1231 This attribute represents the style associated with this keyframe.
1232 </dl>
1235 <h3 id='CSSKeyframesRule-interface'>
1236 Interface <code>CSSKeyframesRule</code></h3>
1238 <p>
1239 The <dfn>CSSKeyframesRule</dfn> interface represents a complete set of keyframes for a single animation.
1242 <h4 id='CSSKeyframesRule-IDL'>
1243 IDL Definition</h4>
1245 <pre class='idl'>
1246 interface CSSKeyframesRule : CSSRule {
1247 attribute DOMString name;
1248 readonly attribute CSSRuleList cssRules;
1250 void appendRule(in DOMString rule);
1251 void deleteRule(in DOMString key);
1252 CSSKeyframeRule findRule(in DOMString key);
1253 };</pre>
1256 <h4 id='CSSKeyframesRule-attributes'>
1257 Attributes</h4>
1259 <dl>
1260 <dt><code><dfn id='CSSKeyframesRule-name'>name</dfn></code> of type <code>DOMString</code>
1261 <dd>
1262 This attribute is the name of the keyframes, used by the 'animation-name' property.<br>
1264 <dt><code><dfn id='CSSKeyframesRules-cssRules'>cssRules</dfn></code> of type <code>CSSRuleList</code>
1265 <dd>
1266 This attribute gives access to the keyframes in the list.
1267 </dl>
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 -->
