css3-animations/Overview.src.html@5e26a796fb84
css3-animations/Overview.src.html
Wed, 20 Feb 2013 20:30:01 -0800
- author
- Sylvain Galineau <sylvaing@microsoft.com>
- date
- Wed, 20 Feb 2013 20:30:01 -0800
- changeset 7517
- 5e26a796fb84
- parent 7504
- 2ccb60ab6e99
- child 7518
- e22f3d171747
- permissions
- -rw-r--r--
[css3-animations] Update editors' list
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:ratan@microsoft.com">Rossen Atanassov</a>
37 (<a class=org href="http://www.microsoft.com/">Microsoft</a>)
38 <dd class=vcard><a class=fn href="http://dbaron.org/">L. David Baron</a>
39 (<a class=org href="http://www.mozilla.org/">Mozilla</a>)
41 <dt>Former editors:
42 <dd><a href="mailto:hyatt@apple.com">David Hyatt</a> (<a
43 href="http://www.apple.com/">Apple Inc</a>)
44 <dd><a href="mailto:cmarrin@apple.com">Chris Marrin</a> (<a
45 href="http://www.apple.com/">Apple Inc</a>)
46 <dd>Sylvain Galineau, Microsoft
48 <dt>Issues list:
49 <dd><a href="https://www.w3.org/Bugs/Public/buglist.cgi?query_format=advanced&product=CSS&component=Animations&resolution=---&cmdtype=doit">in Bugzilla</a>
51 <dt>Discussion:
52 <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>”
54 <dt>Test suite:
55 <dd>none yet
56 </dl>
58 <!--copyright-->
60 <hr title="Separator for header">
61 </div>
63 <h2 class="no-num no-toc" id="abstract">
64 Abstract</h2>
66 <p>
67 This CSS module describes a way for authors to animate the values of CSS properties over time,
68 using keyframes.
69 The behavior of these keyframe animations can be controlled by specifying their duration,
70 number of repeats,
71 and repeating behavior.
74 <h2 class="no-num no-toc" id="status">
75 Status of this document</h2>
76 <!--status-->
79 <h2 class="no-num no-toc" id="contents">
80 Table of contents</h2>
81 <!--toc-->
84 <h2 id="introduction">
85 Introduction</h2>
87 <p><em>This section is not normative.</em>
89 <p>
90 CSS Transitions [[CSS3-TRANSITIONS]]
91 provide a way to interpolate CSS property values
92 when they change as a result of underlying property changes.
93 This provides an easy way to do simple animation,
94 but the start and end states of the animation are controlled by the existing property values,
95 and transitions provide little control to the author on how the animation progresses.
97 <p>
98 This proposal introduces <dfn>defined animations</dfn>,
99 in which the author can specify the changes in CSS properties over time as a set of keyframes.
100 Animations are similar to transitions
101 in that they change the presentational value of CSS properties over time.
102 The principal difference is that
103 while transitions trigger <em>implicitly</em> when property values change,
104 animations are <em>explicitly</em> executed when the animation properties are applied.
105 Because of this,
106 animations require explicit values for the properties being animated.
107 These values are specified using animation keyframes, described below.
109 <p>
110 Many aspects of the animation can be controlled,
111 including how many times the animation iterates,
112 whether or not it alternates between the begin and end values,
113 and whether or not the animation should be running or paused.
114 An animation can also delay its start time.
116 <h2 id="values">
117 Values</h2>
119 <p>
120 This specification follows the <a href="http://www.w3.org/TR/CSS21/about.html#property-defs">CSS property definition conventions</a> from [[!CSS21]].
121 Value types not defined in this specification are defined in CSS Level 2 Revision 1 [[!CSS21]].
122 Other CSS modules may expand the definitions of these value types:
123 for example [[CSS3VAL]], when combined with this module,
124 expands the definition of the <var><length></var> value type as used in this specification.
126 <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.
129 <h2 id="animations">
130 Animations</h2>
132 <p>
133 CSS Animations affect computed property values.
134 During the execution of an animation,
135 the computed value for a property is controlled by the animation.
136 This overrides the value specified in the normal styling system.
137 Animations override all normal rules, but are overriden by
138 !important rules.
140 <p>
141 If at one point in time there are multiple animations specifying behavior for the same property,
142 the animation whose name occurs last in the value of 'animation-name'
143 will override the other animations at that point.
146 <p>
147 An animation does not affect the computed value before the application of the animation,
148 before the animation delay has expired,
149 and after the end of the animation.
152 <div class="figure">
153 <img src="sandwich.png" alt="">
155 <p class="caption">
156 Computation of animated property values
157 </div>
159 <p>
160 The diagram above shows how property values are computed.
161 The intrinsic style is shown at the top of the diagram.
162 The computed value is derived from intrinsic style
163 at the times when an animation is not running
164 and also when an animation is delayed
165 (see below for specification of animation delay).
166 During an animation,
167 the computed style is derived from the animated value.
170 <p>
171 The start time of an animation is the latter of two moments:
172 the time at which the style is resolved that specifies the animation,
173 or the time the document's load event is fired.
174 Therefore, an animation specified in the document style sheet
175 will begin at the document load.
176 An animation specified on an element by modifying the style after the document has loaded
177 will start when the style is resolved.
178 That may be immediately in the case of a pseudo style rule such as hover,
179 or may be when the scripting engine returns control to the browser
180 (in the case of style applied by script).
183 <p>
184 An animation applies to an element
185 if the element has a value for 'animation-name' that references a valid keyframes rule.
186 Once an animation has started
187 it continues until it ends
188 or the 'animation-name' is removed.
189 The values used for the keyframes and animation properties are snapshotted at the time the animation starts.
190 Changing them during the execution of the animation has no effect.
191 Note also that changing the value of 'animation-name' does not necessarily restart an animation
192 (e.g., if a list of animations are applied and one is removed from the list,
193 only that animation will stop;
194 The other animations will continue).
195 In order to restart an animation,
196 it must be removed then reapplied.
199 <p>
200 The end of the animation is defined by the combination of the
201 'animation-duration',
202 'animation-iteration-count' and
203 'animation-fill-mode' properties.
206 <div class="example">
207 <pre>
208 div {
209 animation-name: diagonal-slide;
210 animation-duration: 5s;
211 animation-iteration-count: 10;
212 }
214 @keyframes diagonal-slide {
216 from {
217 left: 0;
218 top: 0;
219 }
221 to {
222 left: 100px;
223 top: 100px;
224 }
226 }</pre>
228 <p>
229 This will produce an animation
230 that moves an element from (0, 0) to (100px, 100px)
231 over five seconds
232 and repeats itself nine times
233 (for a total of ten iterations).
234 </div>
236 <p>
237 Setting the display property to 'none' will terminate any running animation
238 applied to the element and its descendants.
240 If an element has a display of 'none', updating display to a value other than 'none'
241 will start all animations applied to the element by the 'animation-name' property,
242 as well as all animations applied to descendants with display other than 'none'.
243 </p>
245 <p>
246 While authors can use animations to create dynamically changing content,
247 dynamically changing content can lead to seizures in some users.
248 For information on how to avoid content that can lead to seizures, see
249 <a href="http://www.w3.org/TR/WCAG20/#seizure">Guideline 2.3:
250 Seizures:
251 Do not design content in a way that is known to cause seizures</a>
252 ([[WCAG20]]).
253 </p>
255 <h2 id="keyframes">
256 Keyframes</h2>
257 <p>
258 Keyframes are used to specify the values for the animating properties
259 at various points during the animation.
260 The keyframes specify the behavior of one cycle of the animation;
261 the animation may iterate one or more times.
263 <p>
264 Keyframes are specified using a specialized CSS at-rule.
265 A @keyframes rule consists of the keyword "@keyframes",
266 followed by an identifier giving a name for the animation
267 (which will be referenced using 'animation-name'),
268 followed by a set of style rules
269 (delimited by curly braces).
271 <p>
272 The <dfn>keyframe selector</dfn> for a keyframe style rule
273 consists of a comma-separated list of percentage values
274 or the keywords 'from' or 'to'.
275 The selector is used to specify the percentage along the duration of the animation that the keyframe represents.
276 The keyframe itself is specified by the block of property values declared on the selector.
277 The keyword 'from' is equivalent to the value ''0%''.
278 The keyword 'to' is equivalent to the value ''100%''.
279 <span class='note'>Note that the percentage unit specifier must be used on percentage values.
280 Therefore, ''0'' is an invalid keyframe selector.</span>
282 <p>
283 If a ''0%'' or ''from'' keyframe is not specified,
284 then the user agent constructs a ''0%'' keyframe
285 using the computed values of the properties being animated.
286 If a ''100%'' or ''to'' keyframe is not specified,
287 then the user agent constructs a ''100%'' keyframe
288 using the computed values of the properties being animated.
289 If a keyframe selector specifies
290 negative percentage values or
291 values higher than 100%,
292 then the keyframe will be ignored.
294 <p>
295 The <dfn>keyframe declaration block</dfn> for a keyframe rule
296 consists of properties and values.
297 Properties that are unable to be animated are ignored in these rules,
298 with the exception of 'animation-timing-function',
299 the behavior of which is described below. In addition, keyframe rule declarations qualified with !important are ignored.
301 <p class="issue">
302 Need to describe what happens if a property is not present in all keyframes.
304 <p>
305 The @keyframes rule that is used by an animation
306 will be the last one encountered in sorted rules order
307 that matches the name of the animation specified by the 'animation-name' property.
308 @keyframes rules do not cascade;
309 therefore, an animation will never derive keyframes from more than one @keyframes rule.
311 <p class='note'>
312 Note that since empty @keyframes rule are valid, they may hide the keyframes of
313 those preceding animation definitions with a matching name.
315 <p>
316 To determine the set of keyframes,
317 all of the values in the selectors are sorted in increasing order by time.
318 If there are any duplicates,
319 then the last keyframe specified inside the @keyframes rule
320 will be used to provide the keyframe information for that time.
321 There is no cascading within a @keyframes rule if multiple keyframes specify the same keyframe selector values.
323 <p>
324 If a property is not specified for a keyframe,
325 or is specified but invalid,
326 the animation of that property proceeds as if that keyframe did not exist.
327 Conceptually,
328 it is as if a set of keyframes is constructed for each property that is present in any of the keyframes,
329 and an animation is run independently for each property.
331 <div class="example">
332 <pre>
333 @keyframes wobble {
334 0% {
335 left: 100px;
336 }
338 40% {
339 left: 150px;
340 }
342 60% {
343 left: 75px;
344 }
346 100% {
347 left: 100px;
348 }
349 }</pre>
351 <p>
352 Four keyframes are specified for the animation named "wobble".
353 In the first keyframe,
354 shown at the beginning of the animation cycle,
355 the value of the 'left' property being animated is ''100px''.
356 By 40% of the animation duration,
357 'left' has animated to ''150px''.
358 At 60% of the animation duration,
359 'left' has animated back to ''75px''.
360 At the end of the animation cycle,
361 the value of 'left' has returned to ''100px''.
362 The diagram below shows the state of the animation if it were given a duration of ''10s''.
364 <div class="figure">
365 <img src="animation1.png" alt="">
367 <p class="caption">
368 Animations states specified by keyframes
369 </div>
370 </div>
372 <p>
373 The following is the grammar for the keyframes rule.
375 <pre>
376 keyframes_rule: KEYFRAMES_SYM S+ IDENT S* '{' S* keyframes_blocks '}' S*;
378 keyframes_blocks: [ keyframe_selector '{' S* declaration? [ ';' S* declaration? ]* '}' S* ]* ;
380 keyframe_selector: [ FROM_SYM | TO_SYM | PERCENTAGE ] S* [ ',' S* [ FROM_SYM | TO_SYM | PERCENTAGE ] S* ]*;
382 @{K}{E}{Y}{F}{R}{A}{M}{E}{S} {return KEYFRAMES_SYM;}
383 {F}{R}{O}{M} {return FROM_SYM;}
384 {T}{O} {return TO_SYM;}</pre>
387 <h3 id="timing-functions">
388 Timing functions for keyframes</h3>
390 <p>
391 A keyframe style rule may also declare the timing function that is to be used
392 as the animation moves to the next keyframe.
394 <div class="example">
395 <pre>
396 @keyframes bounce {
398 from {
399 top: 100px;
400 animation-timing-function: ease-out;
401 }
403 25% {
404 top: 50px;
405 animation-timing-function: ease-in;
406 }
408 50% {
409 top: 100px;
410 animation-timing-function: ease-out;
411 }
413 75% {
414 top: 75px;
415 animation-timing-function: ease-in;
416 }
418 to {
419 top: 100px;
420 }
422 }</pre>
424 <p>
425 Five keyframes are specified for the animation named "bounce".
426 Between the first and second keyframe
427 (i.e., between 0% and 25%)
428 an ''ease-out'' timing function is used.
429 Between the second and third keyframe
430 (i.e., between 25% and 50%)
431 an ''ease-in'' timing function is used.
432 And so on.
433 The effect will appear as an element that moves up the page ''50px'',
434 slowing down as it reaches its highest point
435 then speeding up as it falls back to ''100px''.
436 The second half of the animation behaves in a similar manner,
437 but only moves the element ''25px'' up the page.
438 </div>
440 <p>
441 A timing function specified on the "to" or 100% keyframe is ignored.
443 <p>
444 See the 'animation-timing-function' property for more information.
447 <h3 id="animation-name-property">
448 The 'animation-name' Property</h3>
450 <p>
451 The 'animation-name' property defines a list of animations that apply.
452 Each name is used to select the keyframe at-rule
453 that provides the property values for the animation.
454 If the name does not match any keyframe at-rule,
455 there are no properties to be animated
456 and the animation will not execute.
457 Furthermore,
458 if the animation name is ''none''
459 then there will be no animation.
460 This can be used to override any animations coming from the cascade.
461 If multiple animations are attempting to modify the same property,
462 then the animation closest to the end of the list of names wins.
464 <p id="list-matching">
465 Each animation listed by name
466 should have a corresponding value for the other animation properties listed below.
467 If the lists of values for the other animation properties do not have the same length,
468 the length of the 'animation-name' list
469 determines the number of items in each list examined when starting animations.
470 The lists are matched up from the first value:
471 excess values at the end are not used.
472 If one of the other properties doesn't have enough comma-separated values to match the number of values of 'animation-name',
473 the UA must calculate its used value by repeating the list of values until there are enough.
474 This truncation or repetition does not affect the computed value.
475 <span class="note">Note: This is analogous to the behavior of the 'background-*'properties,
476 with 'background-image' analogous to 'animation-name'.</span>
479 <table class=propdef>
480 <tr>
481 <th>Name:</th>
482 <td><dfn>animation-name</dfn>
483 <tr>
484 <th><a href="#values">Value</a>:
485 <td><span><single-animation-name></span> [ ',' <span><single-animation-name></span> ]*
486 <tr>
487 <th>Initial:
488 <td>''none''
489 <tr>
490 <th>Applies To:
491 <td>all elements, ::before and ::after pseudo-elements
492 <tr>
493 <th>Inherited:
494 <td>no
495 <tr>
496 <th>Animatable:
497 <td>no
498 <tr>
499 <th>Percentages:
500 <td>N/A
501 <tr>
502 <th>Media:
503 <td>visual
504 <tr>
505 <th>Computed Value:
506 <td>As specified
507 <tr>
508 <th>Canonical Order:
509 <td><abbr title="follows order of property value definition">per grammar</abbr>
510 </table>
512 <div class="prod">
513 <dfn id="single-animation-name"><single-animation-name></dfn> = none | <IDENT>
514 </div>
516 <!--
517 <p>
518 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.
520 <div class="example">
521 <p style="display:none">
522 Example(s):
524 <pre>
525 @keyframes 'border-bloat' {
526 from {
527 border-width: 0;
528 }
529 to {
530 border-width: 10px;
531 }
532 }
534 @keyframes 'border-diet' {
535 from {
536 border-width: 4px;
537 }
538 to {
539 border-width: 2px;
540 }
541 }
543 div {
544 animation-name: 'border-bloat', 'border-diet';
545 animation-duration: 10s, 4s;
546 }
547 </pre>
548 <p>
549 The above example has two animations executing on the same property, 'border-width'. The animations are additive. That is, the
550 resulting value for the property will be the addition of the values from the
551 two animations.
553 <p>
554 At time '0s' the element's border will be 4px wide (0px from 'border-bloat' plus 4px from 'border-diet').
555 At time '4s' the element's border will be 6px wide (4px from 'border-bloat' plus 2px from 'border-diet').
556 At time '10s' the element's border will be 10px wide (10px from 'border-bloat' and no addition from
557 'border-diet' as it is no longer executing).
559 </div>
560 -->
563 <h3 id="animation-duration-property">
564 The 'animation-duration' Property</h3>
566 <p>
567 The 'animation-duration' property defines the length of time that an animation takes to complete one cycle.
570 <table class=propdef>
571 <tr>
572 <th>Name:</th>
573 <td><dfn>animation-duration</dfn>
574 <tr>
575 <th><a href="#values">Value</a>:
576 <td> <span><time></span> [, <span><time></span>]*
577 <tr>
578 <th>Initial:
579 <td>''0s''
580 <tr>
581 <th>Applies To:
582 <td>all elements, ::before and ::after pseudo-elements
583 <tr>
584 <th>Inherited:
585 <td>no
586 <tr>
587 <th>Animatable:
588 <td>no
589 <tr>
590 <th>Percentages:
591 <td>N/A
592 <tr>
593 <th>Media:
594 <td>visual
595 <tr>
596 <th>Computed Value:
597 <td>as specified
598 <tr>
599 <th>Canonical Order:
600 <td><abbr title="follows order of property value definition">per grammar</abbr>
601 </table>
603 <p>
604 The initial value is ''0s'',
605 meaning that the animation takes no time.
606 When the duration is ''0s'' 'animation-fill-mode' still applies,
607 so an animation that fills backwards
608 will show the value of the 0% keyframe during any delay period,
609 and an animation that fills forwards will retain the value specified at the 100% keyframe,
610 even if the animation was instantaneous.
611 Also, animation events are still fired.
612 A negative 'animation-duration' value renders the declaration invalid.
615 <h3 id="animation-timing-function-property">
616 The 'animation-timing-function' Property</h3>
618 <p>
619 The 'animation-timing-function' property describes how the animation will progress over one cycle of its duration.
620 See the 'transition-timing-function' property [[!CSS3-TRANSITIONS]] for a complete description of timing function calculation.
622 <table class=propdef>
623 <tr>
624 <th>Name:</th>
625 <td><dfn>animation-timing-function</dfn>
626 <tr>
627 <th><a href="#values">Value</a>:
628 <td><span><single-timing-function></span> [ ',' <span><single-timing-function></span> ]*
629 <tr>
630 <th>Initial:
631 <td>''ease''
632 <tr>
633 <th>Applies To:
634 <td>all elements, ::before and ::after pseudo-elements
635 <tr>
636 <th>Inherited:
637 <td>no
638 <tr>
639 <th>Animatable:
640 <td>no
641 <tr>
642 <th>Percentages:
643 <td>N/A
644 <tr>
645 <th>Media:
646 <td>visual
647 <tr>
648 <th>Computed Value:
649 <td>as specified
650 <tr>
651 <th>Canonical Order:
652 <td><abbr title="follows order of property value definition">per grammar</abbr>
653 </table>
655 <p>All the valid values of ''<single-timing-function>'' are defined by the 'transition-timing-function' property [[!CSS3-TRANSITIONS]].</p>
657 <p>
658 For a keyframed animation,
659 the 'animation-timing-function' applies between keyframes,
660 not over the entire animation.
661 For example,
662 in the case of an ''ease-in-out'' timing function,
663 an animation will ease in at the start of the keyframe
664 and ease out at the end of the keyframe.
665 An 'animation-timing-function' defined within a keyframe block applies to that keyframe,
666 otherwise the timing function specified for the animation is used.
669 <h3 id="animation-iteration-count-property">
670 The 'animation-iteration-count' Property</h3>
672 <p>
673 The 'animation-iteration-count' property specifies the number of times an animation cycle is played.
674 The initial value is ''1'',
675 meaning the animation will play from beginning to end once.
676 A value of ''infinite'' will cause the animation to repeat forever.
677 Non-integer numbers will cause the animation to end part-way through a cycle.
678 Negative values of 'animation-iteration-count' are invalid.
679 This property is often used in conjunction an 'animation-direction' value of ''alternate'',
680 which will cause the animation to play in reverse on alternate cycles.
682 <table class=propdef>
683 <tr>
684 <th>Name:</th>
685 <td><dfn>animation-iteration-count</dfn>
686 <tr>
687 <th><a href="#values">Value</a>:
688 <td><span><single-animation-iteration-count></span> [ ',' <span><single-animation-iteration-count></span> ]*
689 <tr>
690 <th>Initial:
691 <td>''1''
692 <tr>
693 <th>Applies To:
694 <td>all elements, ::before and ::after pseudo-elements
695 <tr>
696 <th>Inherited:
697 <td>no
698 <tr>
699 <th>Animatable:
700 <td>no
701 <tr>
702 <th>Percentages:
703 <td>N/A
704 <tr>
705 <th>Media:
706 <td>visual
707 <tr>
708 <th>Computed Value:
709 <td>as specified
710 <tr>
711 <th>Canonical Order:
712 <td><abbr title="follows order of property value definition">per grammar</abbr>
713 </table>
715 <div class="prod">
716 <dfn id="single-animation-iteration-count"><single-animation-iteration-count></dfn> =
717 infinite | <number>
718 </div>
720 <h3 id="animation-direction-property">
721 The 'animation-direction' Property</h3>
723 <p>
724 The 'animation-direction' property defines whether or not the animation should play in reverse on some or all cycles.
725 When an animation is played in reverse the timing functions are also reversed.
726 For example, when played in reverse an ease-in animation would appear to be an ease-out animation.
728 <table class=propdef>
729 <tr>
730 <th>Name:</th>
731 <td><dfn>animation-direction</dfn>
732 <tr>
733 <th><a href="#values">Value</a>:
734 <td><span><single-animation-direction></span> [ ',' <span><single-animation-direction></span> ]*
735 <tr>
736 <th>Initial:
737 <td>''normal''
738 <tr>
739 <th>Applies To:
740 <td>all elements, ::before and ::after pseudo-elements
741 <tr>
742 <th>Inherited:
743 <td>no
744 <tr>
745 <th>Animatable:
746 <td>no
747 <tr>
748 <th>Percentages:
749 <td>N/A
750 <tr>
751 <th>Media:
752 <td>visual
753 <tr>
754 <th>Computed Value:
755 <td>as specified
756 <tr>
757 <th>Canonical Order:
758 <td><abbr title="follows order of property value definition">per grammar</abbr>
759 </table>
761 <div class="prod">
762 <dfn id="single-animation-direction"><single-animation-direction></dfn> =
763 normal | reverse | alternate | alternate-reverse
764 </div>
766 <dl>
767 <dt><dfn>normal</dfn>
768 <dd>
769 All iterations of the animation are played as specified.
771 <dt><dfn>reverse</dfn>
772 <dd>
773 All iterations of the animation are played in the reverse direction from the way they were specified.
775 <dt><dfn>alternate</dfn>
776 <dd>
777 The animation cycle iterations that are odd counts are played in the normal direction,
778 and the animation cycle iterations that are even counts are played in a reverse direction.
780 <dt><dfn>alternate-reverse</dfn>
781 <dd>
782 The animation cycle iterations that are odd counts are played in the reverse direction,
783 and the animation cycle iterations that are even counts are played in a normal direction.
784 </dl>
786 <p class='note'>
787 Note that for the purpose of determining whether an iteration is even or odd,
788 iterations start counting from 1.
791 <h3 id="animation-play-state-property">
792 The 'animation-play-state' Property</h3>
794 <p>
795 The 'animation-play-state' property defines whether the animation is running or paused.
796 A running animation can be paused by setting this property to ''paused''.
797 To continue running a paused animation this property can be set to ''running''.
798 A paused animation will continue to display the current value of the animation in a static state,
799 as if the time of the animation is constant.
800 When a paused animation is resumed,
801 it restarts from the current value,
802 not necessarily from the beginning of the animation.
804 <table class=propdef>
805 <tr>
806 <th>Name:</th>
807 <td><dfn>animation-play-state</dfn>
808 <tr>
809 <th><a href="#values">Value</a>:
810 <td><span><single-animation-play-state></span> [ ',' <span><single-animation-play-state></span> ]*
811 <tr>
812 <th>Initial:
813 <td>''running''
814 <tr>
815 <th>Applies To:
816 <td>all elements, ::before and ::after pseudo-elements
817 <tr>
818 <th>Inherited:
819 <td>no
820 <tr>
821 <th>Animatable:
822 <td>no
823 <tr>
824 <th>Percentages:
825 <td>N/A
826 <tr>
827 <th>Media:
828 <td>visual
829 <tr>
830 <th>Computed Value:
831 <td>as specified
832 <tr>
833 <th>Canonical Order:
834 <td><abbr title="follows order of property value definition">per grammar</abbr>
835 </table>
837 <div class="prod">
838 <dfn id="single-animation-play-state"><single-animation-play-state></dfn> =
839 running | paused
840 </div>
842 <h3 id="animation-delay-property">
843 The 'animation-delay' Property</h3>
845 <p>
846 The 'animation-delay' property defines when the animation will start.
847 It allows an animation to begin execution some time after it is applied.
848 An 'animation-delay' value of ''0s'' means the animation will execute as soon as it is applied.
849 Otherwise, the value specifies an offset from the moment the animation is applied,
850 and the animation will delay execution by that offset.
852 <p>
853 If the value for 'animation-delay' is a negative time offset
854 then the animation will execute the moment it is applied,
855 but will appear to have begun execution at the specified offset.
856 That is, the animation will appear to begin part-way through its play cycle.
857 In the case where an animation has implied starting values and a negative 'animation-delay',
858 the starting values are taken from the moment the animation is applied.
860 <table class=propdef>
861 <tr>
862 <th>Name:</th>
863 <td><dfn>animation-delay</dfn>
864 <tr>
865 <th><a href="#values">Value</a>:
866 <td> <span><time></span> [, <span><time></span>]*
867 <tr>
868 <th>Initial:
869 <td>''0s''
870 <tr>
871 <th>Applies To:
872 <td>all elements, ::before and ::after pseudo-elements
873 <tr>
874 <th>Inherited:
875 <td>no
876 <tr>
877 <th>Animatable:
878 <td>no
879 <tr>
880 <th>Percentages:
881 <td>N/A
882 <tr>
883 <th>Media:
884 <td>visual
885 <tr>
886 <th>Computed Value:
887 <td>as specified
888 <tr>
889 <th>Canonical Order:
890 <td><abbr title="follows order of property value definition">per grammar</abbr>
891 </table>
894 <h3 id="animation-fill-mode-property">
895 The 'animation-fill-mode' Property</h3>
897 <p>
898 The 'animation-fill-mode' property defines what values are applied by the animation outside the time it is executing.
899 By default, an animation will not affect property values
900 between the time it is applied
901 (the 'animation-name' property is set on an element)
902 and the time it begins execution
903 (which is determined by the 'animation-delay' property).
904 Also, by default an animation does not affect property values after the animation ends
905 (determined by the 'animation-duration' property).
906 The 'animation-fill-mode' property can override this behavior.
908 <p>
909 If the value for 'animation-fill-mode' is ''backwards'',
910 then the animation will apply
911 the property values defined in the keyframe
912 that will start the first iteration of the animation,
913 during the period defined by 'animation-delay'.
914 These are either the values of the ''from'' keyframe
915 (when 'animation-direction' is ''normal'' or ''alternate'')
916 or those of the ''to'' keyframe
917 (when 'animation-direction' is ''reverse'' or ''alternate-reverse'').
919 <p>
920 If the value for 'animation-fill-mode' is ''forwards'',
921 then after the animation ends
922 (as determined by its 'animation-iteration-count'),
923 the animation will apply
924 the property values for the time the animation ended.
925 When 'animation-iteration-count' is an integer greater than zero,
926 the values applied will be
927 those for the end of the last completed iteration of the animation
928 (rather than the values for
929 the start of the iteration that would be next).
930 When 'animation-iteration-count' is zero,
931 the values applied will be those that would start the first iteration
932 (just as when 'animation-fill-mode' is ''backwards'').
934 <p>
935 If the value for 'animation-fill-mode' is ''both'',
936 then the animation will follow the rules for both 'forwards' and 'backwards'.
937 That is, it will extend the animation properties in both directions.
939 <table class=propdef>
940 <tr>
941 <th>Name:</th>
942 <td><dfn>animation-fill-mode</dfn>
943 <tr>
944 <th><a href="#values">Value</a>:
945 <td><span><single-animation-fill-mode></span> [ ',' <span><single-animation-fill-mode></span> ]*
946 <tr>
947 <th>Initial:
948 <td>''none''
949 <tr>
950 <th>Applies To:
951 <td>all elements, ::before and ::after pseudo-elements
952 <tr>
953 <th>Inherited:
954 <td>no
955 <tr>
956 <th>Animatable:
957 <td>no
958 <tr>
959 <th>Percentages:
960 <td>N/A
961 <tr>
962 <th>Media:
963 <td>visual
964 <tr>
965 <th>Computed Value:
966 <td>as specified
967 <tr>
968 <th>Canonical Order:
969 <td><abbr title="follows order of property value definition">per grammar</abbr>
970 </table>
972 <div class="prod">
973 <dfn id="single-animation-fill-mode"><single-animation-fill-mode></dfn> =
974 none | forwards | backwards | both
975 </div>
977 <h3 id="animation-shorthand-property">
978 The 'animation' Shorthand Property</h3>
980 <p>
981 The 'animation' shorthand property is a comma-separated list of
982 animation definitions, each of which combines seven of the animation properties
983 into a single component value.
985 <table class=propdef>
986 <tr>
987 <th>Name:</th>
988 <td><dfn>animation</dfn>
989 <tr>
990 <th><a href="#values">Value</a>:
991 <td><span><single-animation></span> [ ',' <span><single-animation></span> ]*
992 <tr>
993 <th>Initial:
994 <td>see individual properties
995 <tr>
996 <th>Applies To:
997 <td>all elements, ::before and ::after pseudo-elements
998 <tr>
999 <th>Inherited:
1000 <td>see individual properties
1001 <tr>
1002 <th>Animatable:
1003 <td>no
1004 <tr>
1005 <th>Percentages:
1006 <td>N/A
1007 <tr>
1008 <th>Media:
1009 <td>visual
1010 <tr>
1011 <th>Computed Value:
1012 <td>see individual properties
1013 <tr>
1014 <th>Canonical Order:
1015 <td><abbr title="follows order of property value definition">per grammar</abbr>
1016 </table>
1018 <div class="prod">
1019 <dfn id="single-animation"><single-animation></dfn> =
1020 <single-animation-name> ||
1021 <span><time></span> ||
1022 <single-animation-timing-function> ||
1023 <span><time></span> ||
1024 <single-animation-iteration-count> ||
1025 <single-animation-direction> ||
1026 <single-animation-fill-mode> ||
1027 <single-animation-play-state>
1028 </div>
1030 <p>
1031 Note that order is important within each animation definition:
1032 the first value that can be parsed as a <var><time></var> is assigned to the
1033 animation-duration,
1034 and the second value that can be parsed as a <var><time></var> is assigned to
1035 animation-delay.
1036 </p>
1038 <p class="issue">
1039 An alternative proposal is to accept the font shorthand approach
1040 of using a "/" character between the values of the same type.
1041 e.g. 2s/4s would mean a duration of 2 seconds and a delay of 4 seconds.
1043 <p class="issue">
1044 Need to also explain how order is important in terms of animation-name
1045 versus keywords, and probably also adjust the canonical order to
1046 match.
1048 <h2 id="animation-events">
1049 Animation Events</h2>
1051 <p>
1052 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>.
1053 The start and end of an animation,
1054 and the end of each iteration of an animation,
1055 all generate DOM events.
1056 An element can have multiple properties being animated simultaneously.
1057 This can occur either with a single 'animation-name' value
1058 with keyframes containing multiple properties,
1059 or with multiple 'animation-name' values.
1060 For the purposes of events,
1061 each 'animation-name' specifies a single animation.
1062 Therefore an event will be generated for each 'animation-name' value
1063 and not necessarily for each property being animated.
1065 <p>
1066 Any animation for which both a valid keyframe rule and a non-zero duration are
1067 defined will run and generate events; this includes animations with empty
1068 keyframe rules.
1070 <p>
1071 The time the animation has been running is sent with each event generated.
1072 This allows the event handler to determine the current iteration of a looping animation
1073 or the current position of an alternating animation.
1074 This time does not include any time the animation was in the ''paused'' play state.
1077 <h3 id='AnimationEvent-interface'>
1078 Interface <code>AnimationEvent</code></h3>
1080 <p>
1081 The <dfn>AnimationEvent</dfn> interface provides specific contextual information associated with Animation events.
1084 <h4 id='AnimationEvent-IDL'>
1085 IDL Definition</h4>
1087 <pre class='idl'>
1088 [Constructor(DOMString <var title="">type</var>, optional <i>AnimationEventInit</i> <var title="">animationEventInitDict</var>)]
1089 interface AnimationEvent : <a class="external" href="http://dvcs.w3.org/hg/domcore/raw-file/tip/Overview.html#event">Event</a> {
1090 readonly attribute DOMString <a href="#AnimationEvent-animationName" title="AnimationEvent-lengthComputable">animationName</a>;
1091 readonly attribute float <a href="#AnimationEvent-elapsedTime" title="dom-ProgressEvent-loaded">elapsedTime</a>;
1092 readonly attribute DOMString <a href="#AnimationEvent-pseudoElement" title="AnimationEvent-pseudoElement">pseudoElement</a>;
1093 };
1095 dictionary <dfn id="AnimationEventInit">AnimationEventInit</dfn> : <a class="external" href="http://dvcs.w3.org/hg/domcore/raw-file/tip/Overview.html#eventinit">EventInit</a> {
1096 DOMString <span title="AnimationEventInit-animationName">animationName</span>;
1097 float <span title="AnimationEventInit-loaded">elapsedTime</span>;
1098 DOMString <span title="AnimationEventInit-pseudoElement">pseudoElement</span>;
1099 }
1101 </pre>
1104 <h4 id='AnimationEvent-attributes'>
1105 Attributes</h4>
1107 <dl>
1108 <dt><code><dfn id='AnimationEvent-animationName'>animationName</dfn></code> of type <code>DOMString</code>, readonly
1109 <dd>
1110 The value of the 'animation-name' property of the animation that fired the event.
1112 <dt><code><dfn id='AnimationEvent-elapsedTime'>elapsedTime</dfn></code> of type <code>float</code>, readonly
1113 <dd>
1114 The amount of time the animation has been running,
1115 in seconds,
1116 when this event fired,
1117 excluding any time the animation was paused.
1118 For an "animationstart" event,
1119 the elapsedTime is zero unless there was a negative value for 'animation-delay',
1120 in which case the event will be fired with an <code>elapsedTime</code> of (-1 * delay).
1122 <dt><code><dfn id='AnimationEvent-pseudoElement'>pseudoElement</dfn></code> of type <code>DOMString</code>, readonly
1123 <dd>
1124 The name (beginning with two colons) of the CSS pseudo-element on
1125 which the animation runs (in which case the target of the event
1126 is that pseudo-element's corresponding element), or the empty string
1127 if the animation runs on an element (which means the target of the event
1128 is that element).
1129 </dl>
1131 <p>
1132 <code id="AnimationEvent-constructor">AnimationEvent(type, animationEventInitDict)</code>
1133 is an <a class="external" href="http://dvcs.w3.org/hg/domcore/raw-file/tip/Overview.html#concept-event-constructor">event constructor</a>.
1135 <h3 id='AnimationEvent-types'>
1136 Types of <code>AnimationEvent</code></h3>
1138 <p>
1139 The different types of Animation events that can occur are:
1141 <dl>
1142 <dt><dfn>animationstart</dfn>
1143 <dd>
1144 The <code>animationstart</code> event occurs at the start of the animation.
1145 If there is an 'animation-delay'
1146 then this event will fire once the delay period has expired.
1147 A negative delay will cause the event to fire with an <code>elapsedTime</code> equal to the absolute value of the delay.
1149 <ul>
1150 <li>Bubbles: Yes
1151 <li>Cancelable: No
1152 <li>Context Info: animationName, pseudoElement
1153 </ul>
1155 <dt><dfn>animationend</dfn>
1156 <dd>
1157 The <code>animationend</code> event occurs when the animation finishes.
1159 <ul>
1160 <li>Bubbles: Yes
1161 <li>Cancelable: No
1162 <li>Context Info: animationName, elapsedTime, pseudoElement
1163 </ul>
1165 <dt><dfn>animationiteration</dfn>
1166 <dd>
1167 The <code>animationiteration</code> event occurs at the end of each iteration of an animation,
1168 except when an <code>animationend</code> event would fire at the same time.
1169 This means that this event does not occur for animations with an iteration count of one or less.
1171 <ul>
1172 <li>Bubbles: Yes
1173 <li>Cancelable: No
1174 <li>Context Info: animationName, elapsedTime, pseudoElement
1175 </ul>
1176 </dl>
1179 <h2 id="dom-interfaces">
1180 DOM Interfaces</h2>
1182 <p>
1183 CSS animation is exposed to the CSSOM through a pair of new interfaces describing the keyframes.
1186 <h3 id='CSSRule-interface'>
1187 Interface <code>CSSRule</code></h3>
1189 <p>
1190 The following 2 rule types are added to the <dfn>CSSRule</dfn> interface.
1191 They provide identification for the new keyframe and keyframes rules.
1194 <h4 id='CSSRule-IDL'>
1195 IDL Definition</h4>
1197 <pre class='idl'>
1198 interface CSSRule {
1199 ...
1200 const unsigned short KEYFRAMES_RULE = 7;
1201 const unsigned short KEYFRAME_RULE = 8;
1202 ...
1203 };</pre>
1206 <h3 id='CSSKeyframeRule-interface'>
1207 Interface <code>CSSKeyframeRule</code></h3>
1208 <p>
1209 The <dfn>CSSKeyframeRule</dfn> interface represents the style rule for a single key.
1212 <h4 id='CSSKeyframeRule-IDL'>
1213 IDL Definition</h4>
1215 <pre class='idl'>
1216 interface CSSKeyframeRule : CSSRule {
1217 attribute DOMString keyText;
1218 readonly attribute CSSStyleDeclaration style;
1219 };</pre>
1222 <h4 id='CSSKeyframeRule-attributes'>
1223 Attributes</h4>
1225 <dl>
1226 <dt><code><dfn id='CSSKeyframeRule-keyText'>keyText</dfn></code> of type <code>DOMString</code>
1227 <dd>
1228 This attribute represents the keyframe selector as a comma-separated
1229 list of percentage values. The ''from'' and ''to'' keywords map to
1230 ''0%'' and ''100%'', respectively.
1232 <dt><code><dfn id='CSSKeyframeRule-style'>style</dfn></code> of type <code>CSSStyleDeclaration</code>
1233 <dd>
1234 This attribute represents the style associated with this keyframe.
1235 </dl>
1238 <h3 id='CSSKeyframesRule-interface'>
1239 Interface <code>CSSKeyframesRule</code></h3>
1241 <p>
1242 The <dfn>CSSKeyframesRule</dfn> interface represents a complete set of keyframes for a single animation.
1245 <h4 id='CSSKeyframesRule-IDL'>
1246 IDL Definition</h4>
1248 <pre class='idl'>
1249 interface CSSKeyframesRule : CSSRule {
1250 attribute DOMString name;
1251 readonly attribute CSSRuleList cssRules;
1253 void appendRule(in DOMString rule);
1254 void deleteRule(in DOMString key);
1255 CSSKeyframeRule findRule(in DOMString key);
1256 };</pre>
1259 <h4 id='CSSKeyframesRule-attributes'>
1260 Attributes</h4>
1262 <dl>
1263 <dt><code><dfn id='CSSKeyframesRule-name'>name</dfn></code> of type <code>DOMString</code>
1264 <dd>
1265 This attribute is the name of the keyframes, used by the 'animation-name' property.<br>
1267 <dt><code><dfn id='CSSKeyframesRules-cssRules'>cssRules</dfn></code> of type <code>CSSRuleList</code>
1268 <dd>
1269 This attribute gives access to the keyframes in the list.
1270 </dl>
1273 <h4 id='CSSKeyframesRule-appendRule'>
1274 The <code>appendRule</code> method</h4>
1276 <p>
1277 The <dfn>appendRule</dfn> method appends the passed CSSKeyframeRule into the list at the passed key.
1279 <p>
1280 Parameters:
1282 <dl>
1283 <dt><code>rule</code> of type <code>DOMString</code>
1285 <dd>
1286 The rule to be appended,
1287 expressed in the same syntax as one entry in the ''@keyframes'' rule.
1288 </dl>
1290 <p>
1291 No Return Value
1293 <p>
1294 No Exceptions
1297 <h4 id='CSSKeyframesRules-deleteRule'>
1298 The <code>deleteRule</code> method</h4>
1300 <p>
1301 The <dfn>deleteRule</dfn> method deletes the CSSKeyframeRule with the passed key.
1302 If a rule with this key does not exist,
1303 the method does nothing.
1305 <p>
1306 Parameters:
1308 <dl>
1309 <dt><code>key</code> of type <code>DOMString</code>
1310 <dd>
1311 The key which describes the rule to be deleted.
1312 The key must resolve to a number between 0 and 1,
1313 or the rule is ignored.
1314 </dl>
1316 <p>
1317 No Return Value
1319 <p>
1320 No Exceptions
1323 <h4 id='CSSKeyframesRule-findRule'>
1324 The <code>findRule</code> method</h4>
1326 <p>
1327 The <code>findRule</code> method returns the rule with a key matching the passed key.
1328 If no such rule exists,
1329 a null value is returned.
1331 <p>
1332 Parameters:
1334 <dl>
1335 <dt><code>key</code> of type <code>DOMString</code>
1336 <dd>
1337 The key which described the rule to find.
1338 The key must resolve to a number between 0 and 1,
1339 or the rule is ignored.
1340 </dl>
1342 <p>
1343 Return Value:
1345 <dl>
1346 <dt><code>CSSKeyframeRule</code>
1347 <dd>
1348 The found rule.
1349 </dl>
1351 <p>
1352 No Exceptions
1355 <h2 id="acknowledgments">Acknowledgments</h2>
1357 <p>Thanks especially to the feedback from
1358 Tab Atkins,
1359 Carine Bournez,
1360 Estelle Weyl,
1361 and all the rest of the
1362 <a href="http://lists.w3.org/Archives/Public/www-style/">www-style</a> community.
1364 <h2>References</h2>
1366 <h3 class="no-num">Normative references</h3>
1367 <!--normative-->
1369 <h3 class="no-num">Other references</h3>
1370 <!--informative-->
1374 <h2 class="no-num">Property index</h2>
1375 <!-- properties -->
1379 <h2 class="no-num" id="index">Index</h2>
1380 <!--index-->
1382 </body>
1383 </html>
1384 <!-- Keep this comment at the end of the file
1385 Local variables:
1386 mode: sgml
1387 sgml-declaration:"~/SGML/HTML4.decl"
1388 sgml-default-doctype-name:"html"
1389 sgml-minimize-attributes:t
1390 sgml-nofill-elements:("pre" "style" "br")
1391 sgml-live-element-indicator:t
1392 sgml-omittag:nil
1393 sgml-shorttag:nil
1394 sgml-namecase-general:t
1395 sgml-general-insert-case:lower
1396 sgml-always-quote-attributes:t
1397 sgml-indent-step:nil
1398 sgml-indent-data:t
1399 sgml-parent-document:nil
1400 sgml-exposed-tags:nil
1401 sgml-local-catalogs:nil
1402 sgml-local-ecat-files:nil
1403 End:
1404 -->
