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