css3-animations/Overview.src.html@e22f3d171747
css3-animations/Overview.src.html
Wed, 20 Feb 2013 20:44:27 -0800
- author
- Sylvain Galineau <sylvaing@microsoft.com>
- date
- Wed, 20 Feb 2013 20:44:27 -0800
- changeset 7518
- e22f3d171747
- parent 7517
- 5e26a796fb84
- child 7529
- 01d3f8204e5d
- permissions
- -rw-r--r--
[css3-animations] Clarify animation application (bug 14779)
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 its name appears as one of the identifiers in the
186 computed value of the 'animation-name' property.
187 Once an animation has started
188 it continues until it ends
189 or the 'animation-name' is removed.
190 The values used for the keyframes and animation properties are snapshotted at the time the animation starts.
191 Changing them during the execution of the animation has no effect.
192 Note also that changing the value of 'animation-name' does not necessarily restart an animation
193 (e.g., if a list of animations are applied and one is removed from the list,
194 only that animation will stop;
195 The other animations will continue).
196 In order to restart an animation,
197 it must be removed then reapplied.
200 <p>
201 The end of the animation is defined by the combination of the
202 'animation-duration',
203 'animation-iteration-count' and
204 'animation-fill-mode' properties.
207 <div class="example">
208 <pre>
209 div {
210 animation-name: diagonal-slide;
211 animation-duration: 5s;
212 animation-iteration-count: 10;
213 }
215 @keyframes diagonal-slide {
217 from {
218 left: 0;
219 top: 0;
220 }
222 to {
223 left: 100px;
224 top: 100px;
225 }
227 }</pre>
229 <p>
230 This will produce an animation
231 that moves an element from (0, 0) to (100px, 100px)
232 over five seconds
233 and repeats itself nine times
234 (for a total of ten iterations).
235 </div>
237 <p>
238 Setting the display property to 'none' will terminate any running animation
239 applied to the element and its descendants.
241 If an element has a display of 'none', updating display to a value other than 'none'
242 will start all animations applied to the element by the 'animation-name' property,
243 as well as all animations applied to descendants with display other than 'none'.
244 </p>
246 <p>
247 While authors can use animations to create dynamically changing content,
248 dynamically changing content can lead to seizures in some users.
249 For information on how to avoid content that can lead to seizures, see
250 <a href="http://www.w3.org/TR/WCAG20/#seizure">Guideline 2.3:
251 Seizures:
252 Do not design content in a way that is known to cause seizures</a>
253 ([[WCAG20]]).
254 </p>
256 <h2 id="keyframes">
257 Keyframes</h2>
258 <p>
259 Keyframes are used to specify the values for the animating properties
260 at various points during the animation.
261 The keyframes specify the behavior of one cycle of the animation;
262 the animation may iterate one or more times.
264 <p>
265 Keyframes are specified using a specialized CSS at-rule.
266 A @keyframes rule consists of the keyword "@keyframes",
267 followed by an identifier giving a name for the animation
268 (which will be referenced using 'animation-name'),
269 followed by a set of style rules
270 (delimited by curly braces).
272 <p>
273 The <dfn>keyframe selector</dfn> for a keyframe style rule
274 consists of a comma-separated list of percentage values
275 or the keywords 'from' or 'to'.
276 The selector is used to specify the percentage along the duration of the animation that the keyframe represents.
277 The keyframe itself is specified by the block of property values declared on the selector.
278 The keyword 'from' is equivalent to the value ''0%''.
279 The keyword 'to' is equivalent to the value ''100%''.
280 <span class='note'>Note that the percentage unit specifier must be used on percentage values.
281 Therefore, ''0'' is an invalid keyframe selector.</span>
283 <p>
284 If a ''0%'' or ''from'' keyframe is not specified,
285 then the user agent constructs a ''0%'' keyframe
286 using the computed values of the properties being animated.
287 If a ''100%'' or ''to'' keyframe is not specified,
288 then the user agent constructs a ''100%'' keyframe
289 using the computed values of the properties being animated.
290 If a keyframe selector specifies
291 negative percentage values or
292 values higher than 100%,
293 then the keyframe will be ignored.
295 <p>
296 The <dfn>keyframe declaration block</dfn> for a keyframe rule
297 consists of properties and values.
298 Properties that are unable to be animated are ignored in these rules,
299 with the exception of 'animation-timing-function',
300 the behavior of which is described below. In addition, keyframe rule declarations qualified with !important are ignored.
302 <p class="issue">
303 Need to describe what happens if a property is not present in all keyframes.
305 <p>
306 The @keyframes rule that is used by an animation
307 will be the last one encountered in sorted rules order
308 that matches the name of the animation specified by the 'animation-name' property.
309 @keyframes rules do not cascade;
310 therefore, an animation will never derive keyframes from more than one @keyframes rule.
312 <p class='note'>
313 Note that since empty @keyframes rule are valid, they may hide the keyframes of
314 those preceding animation definitions with a matching name.
316 <p>
317 To determine the set of keyframes,
318 all of the values in the selectors are sorted in increasing order by time.
319 If there are any duplicates,
320 then the last keyframe specified inside the @keyframes rule
321 will be used to provide the keyframe information for that time.
322 There is no cascading within a @keyframes rule if multiple keyframes specify the same keyframe selector values.
324 <p>
325 If a property is not specified for a keyframe,
326 or is specified but invalid,
327 the animation of that property proceeds as if that keyframe did not exist.
328 Conceptually,
329 it is as if a set of keyframes is constructed for each property that is present in any of the keyframes,
330 and an animation is run independently for each property.
332 <div class="example">
333 <pre>
334 @keyframes wobble {
335 0% {
336 left: 100px;
337 }
339 40% {
340 left: 150px;
341 }
343 60% {
344 left: 75px;
345 }
347 100% {
348 left: 100px;
349 }
350 }</pre>
352 <p>
353 Four keyframes are specified for the animation named "wobble".
354 In the first keyframe,
355 shown at the beginning of the animation cycle,
356 the value of the 'left' property being animated is ''100px''.
357 By 40% of the animation duration,
358 'left' has animated to ''150px''.
359 At 60% of the animation duration,
360 'left' has animated back to ''75px''.
361 At the end of the animation cycle,
362 the value of 'left' has returned to ''100px''.
363 The diagram below shows the state of the animation if it were given a duration of ''10s''.
365 <div class="figure">
366 <img src="animation1.png" alt="">
368 <p class="caption">
369 Animations states specified by keyframes
370 </div>
371 </div>
373 <p>
374 The following is the grammar for the keyframes rule.
376 <pre>
377 keyframes_rule: KEYFRAMES_SYM S+ IDENT S* '{' S* keyframes_blocks '}' S*;
379 keyframes_blocks: [ keyframe_selector '{' S* declaration? [ ';' S* declaration? ]* '}' S* ]* ;
381 keyframe_selector: [ FROM_SYM | TO_SYM | PERCENTAGE ] S* [ ',' S* [ FROM_SYM | TO_SYM | PERCENTAGE ] S* ]*;
383 @{K}{E}{Y}{F}{R}{A}{M}{E}{S} {return KEYFRAMES_SYM;}
384 {F}{R}{O}{M} {return FROM_SYM;}
385 {T}{O} {return TO_SYM;}</pre>
388 <h3 id="timing-functions">
389 Timing functions for keyframes</h3>
391 <p>
392 A keyframe style rule may also declare the timing function that is to be used
393 as the animation moves to the next keyframe.
395 <div class="example">
396 <pre>
397 @keyframes bounce {
399 from {
400 top: 100px;
401 animation-timing-function: ease-out;
402 }
404 25% {
405 top: 50px;
406 animation-timing-function: ease-in;
407 }
409 50% {
410 top: 100px;
411 animation-timing-function: ease-out;
412 }
414 75% {
415 top: 75px;
416 animation-timing-function: ease-in;
417 }
419 to {
420 top: 100px;
421 }
423 }</pre>
425 <p>
426 Five keyframes are specified for the animation named "bounce".
427 Between the first and second keyframe
428 (i.e., between 0% and 25%)
429 an ''ease-out'' timing function is used.
430 Between the second and third keyframe
431 (i.e., between 25% and 50%)
432 an ''ease-in'' timing function is used.
433 And so on.
434 The effect will appear as an element that moves up the page ''50px'',
435 slowing down as it reaches its highest point
436 then speeding up as it falls back to ''100px''.
437 The second half of the animation behaves in a similar manner,
438 but only moves the element ''25px'' up the page.
439 </div>
441 <p>
442 A timing function specified on the "to" or 100% keyframe is ignored.
444 <p>
445 See the 'animation-timing-function' property for more information.
448 <h3 id="animation-name-property">
449 The 'animation-name' Property</h3>
451 <p>
452 The 'animation-name' property defines a list of animations that apply.
453 Each name is used to select the keyframe at-rule
454 that provides the property values for the animation.
455 If the name does not match any keyframe at-rule,
456 there are no properties to be animated
457 and the animation will not execute.
458 Furthermore,
459 if the animation name is ''none''
460 then there will be no animation.
461 This can be used to override any animations coming from the cascade.
462 If multiple animations are attempting to modify the same property,
463 then the animation closest to the end of the list of names wins.
465 <p id="list-matching">
466 Each animation listed by name
467 should have a corresponding value for the other animation properties listed below.
468 If the lists of values for the other animation properties do not have the same length,
469 the length of the 'animation-name' list
470 determines the number of items in each list examined when starting animations.
471 The lists are matched up from the first value:
472 excess values at the end are not used.
473 If one of the other properties doesn't have enough comma-separated values to match the number of values of 'animation-name',
474 the UA must calculate its used value by repeating the list of values until there are enough.
475 This truncation or repetition does not affect the computed value.
476 <span class="note">Note: This is analogous to the behavior of the 'background-*'properties,
477 with 'background-image' analogous to 'animation-name'.</span>
480 <table class=propdef>
481 <tr>
482 <th>Name:</th>
483 <td><dfn>animation-name</dfn>
484 <tr>
485 <th><a href="#values">Value</a>:
486 <td><span><single-animation-name></span> [ ',' <span><single-animation-name></span> ]*
487 <tr>
488 <th>Initial:
489 <td>''none''
490 <tr>
491 <th>Applies To:
492 <td>all elements, ::before and ::after pseudo-elements
493 <tr>
494 <th>Inherited:
495 <td>no
496 <tr>
497 <th>Animatable:
498 <td>no
499 <tr>
500 <th>Percentages:
501 <td>N/A
502 <tr>
503 <th>Media:
504 <td>visual
505 <tr>
506 <th>Computed Value:
507 <td>As specified
508 <tr>
509 <th>Canonical Order:
510 <td><abbr title="follows order of property value definition">per grammar</abbr>
511 </table>
513 <div class="prod">
514 <dfn id="single-animation-name"><single-animation-name></dfn> = none | <IDENT>
515 </div>
517 <!--
518 <p>
519 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.
521 <div class="example">
522 <p style="display:none">
523 Example(s):
525 <pre>
526 @keyframes 'border-bloat' {
527 from {
528 border-width: 0;
529 }
530 to {
531 border-width: 10px;
532 }
533 }
535 @keyframes 'border-diet' {
536 from {
537 border-width: 4px;
538 }
539 to {
540 border-width: 2px;
541 }
542 }
544 div {
545 animation-name: 'border-bloat', 'border-diet';
546 animation-duration: 10s, 4s;
547 }
548 </pre>
549 <p>
550 The above example has two animations executing on the same property, 'border-width'. The animations are additive. That is, the
551 resulting value for the property will be the addition of the values from the
552 two animations.
554 <p>
555 At time '0s' the element's border will be 4px wide (0px from 'border-bloat' plus 4px from 'border-diet').
556 At time '4s' the element's border will be 6px wide (4px from 'border-bloat' plus 2px from 'border-diet').
557 At time '10s' the element's border will be 10px wide (10px from 'border-bloat' and no addition from
558 'border-diet' as it is no longer executing).
560 </div>
561 -->
564 <h3 id="animation-duration-property">
565 The 'animation-duration' Property</h3>
567 <p>
568 The 'animation-duration' property defines the length of time that an animation takes to complete one cycle.
571 <table class=propdef>
572 <tr>
573 <th>Name:</th>
574 <td><dfn>animation-duration</dfn>
575 <tr>
576 <th><a href="#values">Value</a>:
577 <td> <span><time></span> [, <span><time></span>]*
578 <tr>
579 <th>Initial:
580 <td>''0s''
581 <tr>
582 <th>Applies To:
583 <td>all elements, ::before and ::after pseudo-elements
584 <tr>
585 <th>Inherited:
586 <td>no
587 <tr>
588 <th>Animatable:
589 <td>no
590 <tr>
591 <th>Percentages:
592 <td>N/A
593 <tr>
594 <th>Media:
595 <td>visual
596 <tr>
597 <th>Computed Value:
598 <td>as specified
599 <tr>
600 <th>Canonical Order:
601 <td><abbr title="follows order of property value definition">per grammar</abbr>
602 </table>
604 <p>
605 The initial value is ''0s'',
606 meaning that the animation takes no time.
607 When the duration is ''0s'' 'animation-fill-mode' still applies,
608 so an animation that fills backwards
609 will show the value of the 0% keyframe during any delay period,
610 and an animation that fills forwards will retain the value specified at the 100% keyframe,
611 even if the animation was instantaneous.
612 Also, animation events are still fired.
613 A negative 'animation-duration' value renders the declaration invalid.
616 <h3 id="animation-timing-function-property">
617 The 'animation-timing-function' Property</h3>
619 <p>
620 The 'animation-timing-function' property describes how the animation will progress over one cycle of its duration.
621 See the 'transition-timing-function' property [[!CSS3-TRANSITIONS]] for a complete description of timing function calculation.
623 <table class=propdef>
624 <tr>
625 <th>Name:</th>
626 <td><dfn>animation-timing-function</dfn>
627 <tr>
628 <th><a href="#values">Value</a>:
629 <td><span><single-timing-function></span> [ ',' <span><single-timing-function></span> ]*
630 <tr>
631 <th>Initial:
632 <td>''ease''
633 <tr>
634 <th>Applies To:
635 <td>all elements, ::before and ::after pseudo-elements
636 <tr>
637 <th>Inherited:
638 <td>no
639 <tr>
640 <th>Animatable:
641 <td>no
642 <tr>
643 <th>Percentages:
644 <td>N/A
645 <tr>
646 <th>Media:
647 <td>visual
648 <tr>
649 <th>Computed Value:
650 <td>as specified
651 <tr>
652 <th>Canonical Order:
653 <td><abbr title="follows order of property value definition">per grammar</abbr>
654 </table>
656 <p>All the valid values of ''<single-timing-function>'' are defined by the 'transition-timing-function' property [[!CSS3-TRANSITIONS]].</p>
658 <p>
659 For a keyframed animation,
660 the 'animation-timing-function' applies between keyframes,
661 not over the entire animation.
662 For example,
663 in the case of an ''ease-in-out'' timing function,
664 an animation will ease in at the start of the keyframe
665 and ease out at the end of the keyframe.
666 An 'animation-timing-function' defined within a keyframe block applies to that keyframe,
667 otherwise the timing function specified for the animation is used.
670 <h3 id="animation-iteration-count-property">
671 The 'animation-iteration-count' Property</h3>
673 <p>
674 The 'animation-iteration-count' property specifies the number of times an animation cycle is played.
675 The initial value is ''1'',
676 meaning the animation will play from beginning to end once.
677 A value of ''infinite'' will cause the animation to repeat forever.
678 Non-integer numbers will cause the animation to end part-way through a cycle.
679 Negative values of 'animation-iteration-count' are invalid.
680 This property is often used in conjunction an 'animation-direction' value of ''alternate'',
681 which will cause the animation to play in reverse on alternate cycles.
683 <table class=propdef>
684 <tr>
685 <th>Name:</th>
686 <td><dfn>animation-iteration-count</dfn>
687 <tr>
688 <th><a href="#values">Value</a>:
689 <td><span><single-animation-iteration-count></span> [ ',' <span><single-animation-iteration-count></span> ]*
690 <tr>
691 <th>Initial:
692 <td>''1''
693 <tr>
694 <th>Applies To:
695 <td>all elements, ::before and ::after pseudo-elements
696 <tr>
697 <th>Inherited:
698 <td>no
699 <tr>
700 <th>Animatable:
701 <td>no
702 <tr>
703 <th>Percentages:
704 <td>N/A
705 <tr>
706 <th>Media:
707 <td>visual
708 <tr>
709 <th>Computed Value:
710 <td>as specified
711 <tr>
712 <th>Canonical Order:
713 <td><abbr title="follows order of property value definition">per grammar</abbr>
714 </table>
716 <div class="prod">
717 <dfn id="single-animation-iteration-count"><single-animation-iteration-count></dfn> =
718 infinite | <number>
719 </div>
721 <h3 id="animation-direction-property">
722 The 'animation-direction' Property</h3>
724 <p>
725 The 'animation-direction' property defines whether or not the animation should play in reverse on some or all cycles.
726 When an animation is played in reverse the timing functions are also reversed.
727 For example, when played in reverse an ease-in animation would appear to be an ease-out animation.
729 <table class=propdef>
730 <tr>
731 <th>Name:</th>
732 <td><dfn>animation-direction</dfn>
733 <tr>
734 <th><a href="#values">Value</a>:
735 <td><span><single-animation-direction></span> [ ',' <span><single-animation-direction></span> ]*
736 <tr>
737 <th>Initial:
738 <td>''normal''
739 <tr>
740 <th>Applies To:
741 <td>all elements, ::before and ::after pseudo-elements
742 <tr>
743 <th>Inherited:
744 <td>no
745 <tr>
746 <th>Animatable:
747 <td>no
748 <tr>
749 <th>Percentages:
750 <td>N/A
751 <tr>
752 <th>Media:
753 <td>visual
754 <tr>
755 <th>Computed Value:
756 <td>as specified
757 <tr>
758 <th>Canonical Order:
759 <td><abbr title="follows order of property value definition">per grammar</abbr>
760 </table>
762 <div class="prod">
763 <dfn id="single-animation-direction"><single-animation-direction></dfn> =
764 normal | reverse | alternate | alternate-reverse
765 </div>
767 <dl>
768 <dt><dfn>normal</dfn>
769 <dd>
770 All iterations of the animation are played as specified.
772 <dt><dfn>reverse</dfn>
773 <dd>
774 All iterations of the animation are played in the reverse direction from the way they were specified.
776 <dt><dfn>alternate</dfn>
777 <dd>
778 The animation cycle iterations that are odd counts are played in the normal direction,
779 and the animation cycle iterations that are even counts are played in a reverse direction.
781 <dt><dfn>alternate-reverse</dfn>
782 <dd>
783 The animation cycle iterations that are odd counts are played in the reverse direction,
784 and the animation cycle iterations that are even counts are played in a normal direction.
785 </dl>
787 <p class='note'>
788 Note that for the purpose of determining whether an iteration is even or odd,
789 iterations start counting from 1.
792 <h3 id="animation-play-state-property">
793 The 'animation-play-state' Property</h3>
795 <p>
796 The 'animation-play-state' property defines whether the animation is running or paused.
797 A running animation can be paused by setting this property to ''paused''.
798 To continue running a paused animation this property can be set to ''running''.
799 A paused animation will continue to display the current value of the animation in a static state,
800 as if the time of the animation is constant.
801 When a paused animation is resumed,
802 it restarts from the current value,
803 not necessarily from the beginning of the animation.
805 <table class=propdef>
806 <tr>
807 <th>Name:</th>
808 <td><dfn>animation-play-state</dfn>
809 <tr>
810 <th><a href="#values">Value</a>:
811 <td><span><single-animation-play-state></span> [ ',' <span><single-animation-play-state></span> ]*
812 <tr>
813 <th>Initial:
814 <td>''running''
815 <tr>
816 <th>Applies To:
817 <td>all elements, ::before and ::after pseudo-elements
818 <tr>
819 <th>Inherited:
820 <td>no
821 <tr>
822 <th>Animatable:
823 <td>no
824 <tr>
825 <th>Percentages:
826 <td>N/A
827 <tr>
828 <th>Media:
829 <td>visual
830 <tr>
831 <th>Computed Value:
832 <td>as specified
833 <tr>
834 <th>Canonical Order:
835 <td><abbr title="follows order of property value definition">per grammar</abbr>
836 </table>
838 <div class="prod">
839 <dfn id="single-animation-play-state"><single-animation-play-state></dfn> =
840 running | paused
841 </div>
843 <h3 id="animation-delay-property">
844 The 'animation-delay' Property</h3>
846 <p>
847 The 'animation-delay' property defines when the animation will start.
848 It allows an animation to begin execution some time after it is applied.
849 An 'animation-delay' value of ''0s'' means the animation will execute as soon as it is applied.
850 Otherwise, the value specifies an offset from the moment the animation is applied,
851 and the animation will delay execution by that offset.
853 <p>
854 If the value for 'animation-delay' is a negative time offset
855 then the animation will execute the moment it is applied,
856 but will appear to have begun execution at the specified offset.
857 That is, the animation will appear to begin part-way through its play cycle.
858 In the case where an animation has implied starting values and a negative 'animation-delay',
859 the starting values are taken from the moment the animation is applied.
861 <table class=propdef>
862 <tr>
863 <th>Name:</th>
864 <td><dfn>animation-delay</dfn>
865 <tr>
866 <th><a href="#values">Value</a>:
867 <td> <span><time></span> [, <span><time></span>]*
868 <tr>
869 <th>Initial:
870 <td>''0s''
871 <tr>
872 <th>Applies To:
873 <td>all elements, ::before and ::after pseudo-elements
874 <tr>
875 <th>Inherited:
876 <td>no
877 <tr>
878 <th>Animatable:
879 <td>no
880 <tr>
881 <th>Percentages:
882 <td>N/A
883 <tr>
884 <th>Media:
885 <td>visual
886 <tr>
887 <th>Computed Value:
888 <td>as specified
889 <tr>
890 <th>Canonical Order:
891 <td><abbr title="follows order of property value definition">per grammar</abbr>
892 </table>
895 <h3 id="animation-fill-mode-property">
896 The 'animation-fill-mode' Property</h3>
898 <p>
899 The 'animation-fill-mode' property defines what values are applied by the animation outside the time it is executing.
900 By default, an animation will not affect property values
901 between the time it is applied
902 (the 'animation-name' property is set on an element)
903 and the time it begins execution
904 (which is determined by the 'animation-delay' property).
905 Also, by default an animation does not affect property values after the animation ends
906 (determined by the 'animation-duration' property).
907 The 'animation-fill-mode' property can override this behavior.
909 <p>
910 If the value for 'animation-fill-mode' is ''backwards'',
911 then the animation will apply
912 the property values defined in the keyframe
913 that will start the first iteration of the animation,
914 during the period defined by 'animation-delay'.
915 These are either the values of the ''from'' keyframe
916 (when 'animation-direction' is ''normal'' or ''alternate'')
917 or those of the ''to'' keyframe
918 (when 'animation-direction' is ''reverse'' or ''alternate-reverse'').
920 <p>
921 If the value for 'animation-fill-mode' is ''forwards'',
922 then after the animation ends
923 (as determined by its 'animation-iteration-count'),
924 the animation will apply
925 the property values for the time the animation ended.
926 When 'animation-iteration-count' is an integer greater than zero,
927 the values applied will be
928 those for the end of the last completed iteration of the animation
929 (rather than the values for
930 the start of the iteration that would be next).
931 When 'animation-iteration-count' is zero,
932 the values applied will be those that would start the first iteration
933 (just as when 'animation-fill-mode' is ''backwards'').
935 <p>
936 If the value for 'animation-fill-mode' is ''both'',
937 then the animation will follow the rules for both 'forwards' and 'backwards'.
938 That is, it will extend the animation properties in both directions.
940 <table class=propdef>
941 <tr>
942 <th>Name:</th>
943 <td><dfn>animation-fill-mode</dfn>
944 <tr>
945 <th><a href="#values">Value</a>:
946 <td><span><single-animation-fill-mode></span> [ ',' <span><single-animation-fill-mode></span> ]*
947 <tr>
948 <th>Initial:
949 <td>''none''
950 <tr>
951 <th>Applies To:
952 <td>all elements, ::before and ::after pseudo-elements
953 <tr>
954 <th>Inherited:
955 <td>no
956 <tr>
957 <th>Animatable:
958 <td>no
959 <tr>
960 <th>Percentages:
961 <td>N/A
962 <tr>
963 <th>Media:
964 <td>visual
965 <tr>
966 <th>Computed Value:
967 <td>as specified
968 <tr>
969 <th>Canonical Order:
970 <td><abbr title="follows order of property value definition">per grammar</abbr>
971 </table>
973 <div class="prod">
974 <dfn id="single-animation-fill-mode"><single-animation-fill-mode></dfn> =
975 none | forwards | backwards | both
976 </div>
978 <h3 id="animation-shorthand-property">
979 The 'animation' Shorthand Property</h3>
981 <p>
982 The 'animation' shorthand property is a comma-separated list of
983 animation definitions, each of which combines seven of the animation properties
984 into a single component value.
986 <table class=propdef>
987 <tr>
988 <th>Name:</th>
989 <td><dfn>animation</dfn>
990 <tr>
991 <th><a href="#values">Value</a>:
992 <td><span><single-animation></span> [ ',' <span><single-animation></span> ]*
993 <tr>
994 <th>Initial:
995 <td>see individual properties
996 <tr>
997 <th>Applies To:
998 <td>all elements, ::before and ::after pseudo-elements
999 <tr>
1000 <th>Inherited:
1001 <td>see individual properties
1002 <tr>
1003 <th>Animatable:
1004 <td>no
1005 <tr>
1006 <th>Percentages:
1007 <td>N/A
1008 <tr>
1009 <th>Media:
1010 <td>visual
1011 <tr>
1012 <th>Computed Value:
1013 <td>see individual properties
1014 <tr>
1015 <th>Canonical Order:
1016 <td><abbr title="follows order of property value definition">per grammar</abbr>
1017 </table>
1019 <div class="prod">
1020 <dfn id="single-animation"><single-animation></dfn> =
1021 <single-animation-name> ||
1022 <span><time></span> ||
1023 <single-animation-timing-function> ||
1024 <span><time></span> ||
1025 <single-animation-iteration-count> ||
1026 <single-animation-direction> ||
1027 <single-animation-fill-mode> ||
1028 <single-animation-play-state>
1029 </div>
1031 <p>
1032 Note that order is important within each animation definition:
1033 the first value that can be parsed as a <var><time></var> is assigned to the
1034 animation-duration,
1035 and the second value that can be parsed as a <var><time></var> is assigned to
1036 animation-delay.
1037 </p>
1039 <p class="issue">
1040 An alternative proposal is to accept the font shorthand approach
1041 of using a "/" character between the values of the same type.
1042 e.g. 2s/4s would mean a duration of 2 seconds and a delay of 4 seconds.
1044 <p class="issue">
1045 Need to also explain how order is important in terms of animation-name
1046 versus keywords, and probably also adjust the canonical order to
1047 match.
1049 <h2 id="animation-events">
1050 Animation Events</h2>
1052 <p>
1053 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>.
1054 The start and end of an animation,
1055 and the end of each iteration of an animation,
1056 all generate DOM events.
1057 An element can have multiple properties being animated simultaneously.
1058 This can occur either with a single 'animation-name' value
1059 with keyframes containing multiple properties,
1060 or with multiple 'animation-name' values.
1061 For the purposes of events,
1062 each 'animation-name' specifies a single animation.
1063 Therefore an event will be generated for each 'animation-name' value
1064 and not necessarily for each property being animated.
1066 <p>
1067 Any animation for which both a valid keyframe rule and a non-zero duration are
1068 defined will run and generate events; this includes animations with empty
1069 keyframe rules.
1071 <p>
1072 The time the animation has been running is sent with each event generated.
1073 This allows the event handler to determine the current iteration of a looping animation
1074 or the current position of an alternating animation.
1075 This time does not include any time the animation was in the ''paused'' play state.
1078 <h3 id='AnimationEvent-interface'>
1079 Interface <code>AnimationEvent</code></h3>
1081 <p>
1082 The <dfn>AnimationEvent</dfn> interface provides specific contextual information associated with Animation events.
1085 <h4 id='AnimationEvent-IDL'>
1086 IDL Definition</h4>
1088 <pre class='idl'>
1089 [Constructor(DOMString <var title="">type</var>, optional <i>AnimationEventInit</i> <var title="">animationEventInitDict</var>)]
1090 interface AnimationEvent : <a class="external" href="http://dvcs.w3.org/hg/domcore/raw-file/tip/Overview.html#event">Event</a> {
1091 readonly attribute DOMString <a href="#AnimationEvent-animationName" title="AnimationEvent-lengthComputable">animationName</a>;
1092 readonly attribute float <a href="#AnimationEvent-elapsedTime" title="dom-ProgressEvent-loaded">elapsedTime</a>;
1093 readonly attribute DOMString <a href="#AnimationEvent-pseudoElement" title="AnimationEvent-pseudoElement">pseudoElement</a>;
1094 };
1096 dictionary <dfn id="AnimationEventInit">AnimationEventInit</dfn> : <a class="external" href="http://dvcs.w3.org/hg/domcore/raw-file/tip/Overview.html#eventinit">EventInit</a> {
1097 DOMString <span title="AnimationEventInit-animationName">animationName</span>;
1098 float <span title="AnimationEventInit-loaded">elapsedTime</span>;
1099 DOMString <span title="AnimationEventInit-pseudoElement">pseudoElement</span>;
1100 }
1102 </pre>
1105 <h4 id='AnimationEvent-attributes'>
1106 Attributes</h4>
1108 <dl>
1109 <dt><code><dfn id='AnimationEvent-animationName'>animationName</dfn></code> of type <code>DOMString</code>, readonly
1110 <dd>
1111 The value of the 'animation-name' property of the animation that fired the event.
1113 <dt><code><dfn id='AnimationEvent-elapsedTime'>elapsedTime</dfn></code> of type <code>float</code>, readonly
1114 <dd>
1115 The amount of time the animation has been running,
1116 in seconds,
1117 when this event fired,
1118 excluding any time the animation was paused.
1119 For an "animationstart" event,
1120 the elapsedTime is zero unless there was a negative value for 'animation-delay',
1121 in which case the event will be fired with an <code>elapsedTime</code> of (-1 * delay).
1123 <dt><code><dfn id='AnimationEvent-pseudoElement'>pseudoElement</dfn></code> of type <code>DOMString</code>, readonly
1124 <dd>
1125 The name (beginning with two colons) of the CSS pseudo-element on
1126 which the animation runs (in which case the target of the event
1127 is that pseudo-element's corresponding element), or the empty string
1128 if the animation runs on an element (which means the target of the event
1129 is that element).
1130 </dl>
1132 <p>
1133 <code id="AnimationEvent-constructor">AnimationEvent(type, animationEventInitDict)</code>
1134 is an <a class="external" href="http://dvcs.w3.org/hg/domcore/raw-file/tip/Overview.html#concept-event-constructor">event constructor</a>.
1136 <h3 id='AnimationEvent-types'>
1137 Types of <code>AnimationEvent</code></h3>
1139 <p>
1140 The different types of Animation events that can occur are:
1142 <dl>
1143 <dt><dfn>animationstart</dfn>
1144 <dd>
1145 The <code>animationstart</code> event occurs at the start of the animation.
1146 If there is an 'animation-delay'
1147 then this event will fire once the delay period has expired.
1148 A negative delay will cause the event to fire with an <code>elapsedTime</code> equal to the absolute value of the delay.
1150 <ul>
1151 <li>Bubbles: Yes
1152 <li>Cancelable: No
1153 <li>Context Info: animationName, pseudoElement
1154 </ul>
1156 <dt><dfn>animationend</dfn>
1157 <dd>
1158 The <code>animationend</code> event occurs when the animation finishes.
1160 <ul>
1161 <li>Bubbles: Yes
1162 <li>Cancelable: No
1163 <li>Context Info: animationName, elapsedTime, pseudoElement
1164 </ul>
1166 <dt><dfn>animationiteration</dfn>
1167 <dd>
1168 The <code>animationiteration</code> event occurs at the end of each iteration of an animation,
1169 except when an <code>animationend</code> event would fire at the same time.
1170 This means that this event does not occur for animations with an iteration count of one or less.
1172 <ul>
1173 <li>Bubbles: Yes
1174 <li>Cancelable: No
1175 <li>Context Info: animationName, elapsedTime, pseudoElement
1176 </ul>
1177 </dl>
1180 <h2 id="dom-interfaces">
1181 DOM Interfaces</h2>
1183 <p>
1184 CSS animation is exposed to the CSSOM through a pair of new interfaces describing the keyframes.
1187 <h3 id='CSSRule-interface'>
1188 Interface <code>CSSRule</code></h3>
1190 <p>
1191 The following 2 rule types are added to the <dfn>CSSRule</dfn> interface.
1192 They provide identification for the new keyframe and keyframes rules.
1195 <h4 id='CSSRule-IDL'>
1196 IDL Definition</h4>
1198 <pre class='idl'>
1199 interface CSSRule {
1200 ...
1201 const unsigned short KEYFRAMES_RULE = 7;
1202 const unsigned short KEYFRAME_RULE = 8;
1203 ...
1204 };</pre>
1207 <h3 id='CSSKeyframeRule-interface'>
1208 Interface <code>CSSKeyframeRule</code></h3>
1209 <p>
1210 The <dfn>CSSKeyframeRule</dfn> interface represents the style rule for a single key.
1213 <h4 id='CSSKeyframeRule-IDL'>
1214 IDL Definition</h4>
1216 <pre class='idl'>
1217 interface CSSKeyframeRule : CSSRule {
1218 attribute DOMString keyText;
1219 readonly attribute CSSStyleDeclaration style;
1220 };</pre>
1223 <h4 id='CSSKeyframeRule-attributes'>
1224 Attributes</h4>
1226 <dl>
1227 <dt><code><dfn id='CSSKeyframeRule-keyText'>keyText</dfn></code> of type <code>DOMString</code>
1228 <dd>
1229 This attribute represents the keyframe selector as a comma-separated
1230 list of percentage values. The ''from'' and ''to'' keywords map to
1231 ''0%'' and ''100%'', respectively.
1233 <dt><code><dfn id='CSSKeyframeRule-style'>style</dfn></code> of type <code>CSSStyleDeclaration</code>
1234 <dd>
1235 This attribute represents the style associated with this keyframe.
1236 </dl>
1239 <h3 id='CSSKeyframesRule-interface'>
1240 Interface <code>CSSKeyframesRule</code></h3>
1242 <p>
1243 The <dfn>CSSKeyframesRule</dfn> interface represents a complete set of keyframes for a single animation.
1246 <h4 id='CSSKeyframesRule-IDL'>
1247 IDL Definition</h4>
1249 <pre class='idl'>
1250 interface CSSKeyframesRule : CSSRule {
1251 attribute DOMString name;
1252 readonly attribute CSSRuleList cssRules;
1254 void appendRule(in DOMString rule);
1255 void deleteRule(in DOMString key);
1256 CSSKeyframeRule findRule(in DOMString key);
1257 };</pre>
1260 <h4 id='CSSKeyframesRule-attributes'>
1261 Attributes</h4>
1263 <dl>
1264 <dt><code><dfn id='CSSKeyframesRule-name'>name</dfn></code> of type <code>DOMString</code>
1265 <dd>
1266 This attribute is the name of the keyframes, used by the 'animation-name' property.<br>
1268 <dt><code><dfn id='CSSKeyframesRules-cssRules'>cssRules</dfn></code> of type <code>CSSRuleList</code>
1269 <dd>
1270 This attribute gives access to the keyframes in the list.
1271 </dl>
1274 <h4 id='CSSKeyframesRule-appendRule'>
1275 The <code>appendRule</code> method</h4>
1277 <p>
1278 The <dfn>appendRule</dfn> method appends the passed CSSKeyframeRule into the list at the passed key.
1280 <p>
1281 Parameters:
1283 <dl>
1284 <dt><code>rule</code> of type <code>DOMString</code>
1286 <dd>
1287 The rule to be appended,
1288 expressed in the same syntax as one entry in the ''@keyframes'' rule.
1289 </dl>
1291 <p>
1292 No Return Value
1294 <p>
1295 No Exceptions
1298 <h4 id='CSSKeyframesRules-deleteRule'>
1299 The <code>deleteRule</code> method</h4>
1301 <p>
1302 The <dfn>deleteRule</dfn> method deletes the CSSKeyframeRule with the passed key.
1303 If a rule with this key does not exist,
1304 the method does nothing.
1306 <p>
1307 Parameters:
1309 <dl>
1310 <dt><code>key</code> of type <code>DOMString</code>
1311 <dd>
1312 The key which describes the rule to be deleted.
1313 The key must resolve to a number between 0 and 1,
1314 or the rule is ignored.
1315 </dl>
1317 <p>
1318 No Return Value
1320 <p>
1321 No Exceptions
1324 <h4 id='CSSKeyframesRule-findRule'>
1325 The <code>findRule</code> method</h4>
1327 <p>
1328 The <code>findRule</code> method returns the rule with a key matching the passed key.
1329 If no such rule exists,
1330 a null value is returned.
1332 <p>
1333 Parameters:
1335 <dl>
1336 <dt><code>key</code> of type <code>DOMString</code>
1337 <dd>
1338 The key which described the rule to find.
1339 The key must resolve to a number between 0 and 1,
1340 or the rule is ignored.
1341 </dl>
1343 <p>
1344 Return Value:
1346 <dl>
1347 <dt><code>CSSKeyframeRule</code>
1348 <dd>
1349 The found rule.
1350 </dl>
1352 <p>
1353 No Exceptions
1356 <h2 id="acknowledgments">Acknowledgments</h2>
1358 <p>Thanks especially to the feedback from
1359 Tab Atkins,
1360 Carine Bournez,
1361 Estelle Weyl,
1362 and all the rest of the
1363 <a href="http://lists.w3.org/Archives/Public/www-style/">www-style</a> community.
1365 <h2>References</h2>
1367 <h3 class="no-num">Normative references</h3>
1368 <!--normative-->
1370 <h3 class="no-num">Other references</h3>
1371 <!--informative-->
1375 <h2 class="no-num">Property index</h2>
1376 <!-- properties -->
1380 <h2 class="no-num" id="index">Index</h2>
1381 <!--index-->
1383 </body>
1384 </html>
1385 <!-- Keep this comment at the end of the file
1386 Local variables:
1387 mode: sgml
1388 sgml-declaration:"~/SGML/HTML4.decl"
1389 sgml-default-doctype-name:"html"
1390 sgml-minimize-attributes:t
1391 sgml-nofill-elements:("pre" "style" "br")
1392 sgml-live-element-indicator:t
1393 sgml-omittag:nil
1394 sgml-shorttag:nil
1395 sgml-namecase-general:t
1396 sgml-general-insert-case:lower
1397 sgml-always-quote-attributes:t
1398 sgml-indent-step:nil
1399 sgml-indent-data:t
1400 sgml-parent-document:nil
1401 sgml-exposed-tags:nil
1402 sgml-local-catalogs:nil
1403 sgml-local-ecat-files:nil
1404 End:
1405 -->
