Wed, 28 Mar 2012 22:04:08 -0700
Fix two errors in the grammar of the steps() function: first, add necessary [] so that the comma applies to both the start and end values; second, add the ? that was intended to indicate the second parameter being optional.
1 <!DOCTYPE html PUBLIC '-//W3C//DTD HTML 4.01//EN'
2 'http://www.w3.org/TR/html4/strict.dtd'>
4 <html lang="en">
5 <head>
6 <title>CSS Transitions</title>
7 <link rel="stylesheet" type="text/css" href="../default.css">
8 <style type="text/css">
9 table.animatable-properties {
10 border-collapse: collapse;
11 }
12 table.animatable-properties td {
13 padding: 0.2em 1em;
14 border: 1px solid black;
15 }
16 </style>
17 <link rel="stylesheet" type="text/css" href="http://www.w3.org/StyleSheets/TR/W3C-ED.css">
18 </head>
20 <body>
22 <div class="head">
23 <!--logo-->
25 <h1>CSS Transitions</h1>
27 <h2 class="no-num no-toc">[LONGSTATUS] [DATE]</h2>
28 <dl>
29 <dt>This version:
30 <dd>
31 <a href="[VERSION]">
32 http://dev.w3.org/csswg/css3-transitions/</a>
33 <!--http://www.w3.org/TR/[YEAR]/WD-[SHORTNAME]-[CDATE]-->
34 <dt>Latest version:
35 <dd><a href="http://www.w3.org/TR/css3-transitions">
36 [LATEST]</a>
37 <dt>Editor's draft:
38 <dd><a href="http://dev.w3.org/csswg/[SHORTNAME]/">http://dev.w3.org/csswg/[SHORTNAME]/</a>
39 <dt>Previous version:
40 <dd><a href="http://www.w3.org/TR/2009/WD-css3-transitions-20091201/">
41 http://www.w3.org/TR/2009/WD-css3-transitions-20091201/</a>
42 <dt id="editors-list">Editors:
43 <dd><a href="mailto:dino@apple.com">Dean Jackson</a> (<a
44 href="http://www.apple.com/">Apple Inc</a>)
45 <dd><a href="mailto:hyatt@apple.com">David Hyatt</a> (<a
46 href="http://www.apple.com/">Apple Inc</a>)
47 <dd><a href="mailto:cmarrin@apple.com">Chris Marrin</a> (<a
48 href="http://www.apple.com/">Apple Inc</a>)
49 <dd class=vcard><a class=fn href="http://dbaron.org/">L. David Baron</a> (<a
50 class=org href="http://www.mozilla.com/">Mozilla</a>)
52 <dt>Issues list:
53 <dd><a href="https://www.w3.org/Bugs/Public/buglist.cgi?query_format=advanced&product=CSS&component=Transitions&resolution=---&cmdtype=doit">in Bugzilla</a>
55 <dt>Discussion:</dt>
56 <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>”
58 <dt>Test suite:
59 <dd>none yet
60 </dl>
62 <!--copyright-->
64 <hr title="Separator for header">
65 </div>
67 <h2 class="no-num no-toc" id="abstract">Abstract</h2>
69 <p>CSS Transitions allows property changes in CSS values to occur smoothly
70 over a specified duration.
72 <h2 class="no-num no-toc" id="status">Status of this document</h2>
73 <!--status-->
75 <p>
76 The <a href="ChangeLog">list of changes made to this specification</a> is
77 available.
78 </p>
80 <h2 class="no-num no-toc" id="contents">Table of contents</h2>
81 <!--toc-->
84 <h2 id="introduction">Introduction</h2>
86 <p><em>This section is not normative.</em>
87 <p>
88 This document introduces new CSS features to enable <em>implicit transitions</em>, which describe how CSS properties can be made to change smoothly from one value to another over a given duration.
89 </p>
91 <h2 id="transitions">Transitions</h2>
92 <p>
93 Normally when the value of a CSS property changes, the rendered result is instantly updated, with the affected elements immediately changing from the old property value to the new property value. This section describes a way to specify transitions using new CSS properties. These properties are used to animate smoothly from the old state to the new state over time.
94 </p>
95 <p>
96 For example, suppose that transitions of one second have been defined on the <code class="property">'left'</code> and
97 <code class="property">'background-color'</code> properties. The following diagram illustrates the effect of updating those properties on an element, in this case moving it to the right and changing the background from red to blue. This assumes other transition parameters still have their default values.
98 </p>
99 <div class="figure">
100 <img src="transition1.png" alt="">
101 </div>
102 <p class="caption">
103 Transitions of <code class="property">'left'</code> and <code class="property">'background-color'</code>
104 </p>
105 <p>
106 Transitions are a presentational effect. The computed value of a property transitions over time from the old value to the new value. Therefore if a script queries the computed style of a property as it is transitioning, it will see an intermediate value that represents the current animated value of the property.
107 </p>
108 <p>
109 Only animatable CSS properties can be transitioned. See the table at the end of this document for a list
110 of properties that are animatable.
111 </p>
112 <p>
113 The transition for a property is defined using a number of new properties. For example:
114 </p>
115 <div class="example">
116 <p style="display:none">
117 Example(s):
118 </p>
119 <pre>
120 div {
121 transition-property: opacity;
122 transition-duration: 2s;
123 }
124 </pre>The above example defines a transition on the <code class="property">'opacity'</code> property that, when a new value is assigned to it, will cause a smooth change between the old value and the new value over a period of two seconds.
125 </div>
126 <p>
127 Each of the transition properties accepts a comma-separated list, allowing multiple transitions to be defined, each acting on a different property. In this case, the individual transitions take their parameters from the same index in all the lists. For example:
128 </p>
129 <div class="example">
130 <p style="display:none">
131 Example(s):
132 </p>
133 <pre>
134 div {
135 transition-property: opacity, left;
136 transition-duration: 2s, 4s;
137 }
139 </pre>This will cause the <code class="property">'opacity'</code> property to transition over a period of two seconds and the left property to transition over a period of four seconds.
140 </div>
142 <p id="list-matching">
143 In the case where the lists of values in transition properties
144 do not have the same length, the length of the
145 'transition-property' list determines the number of items in
146 each list examined when starting transitions. The lists are
147 matched up from the first value: excess values at the end are
148 not used. If one of the other properties doesn't have enough
149 comma-separated values to match the number of values of
150 'transition-property', the UA must calculate its used value by
151 repeating the list of values until there are enough. This
152 truncation or repetition does not affect the computed value.
153 <span class="note">
154 Note: This is analogous to the behavior of the 'background-*'
155 properties, with 'background-image' analogous to
156 'transition-property'.
157 </span>
158 </p>
160 <div class="example">
161 <p style="display:none">
162 Example(s):
163 </p>
164 <pre>
165 div {
166 transition-property: opacity, left, top, width;
167 transition-duration: 2s, 1s;
168 }
169 </pre>The above example defines a transition on the <code class="property">'opacity'</code> property of 2 seconds duration, a
170 transition on the <code class="property">'left'</code> property of 1
171 second duration, a transition on the <code class="property">'top'</code> property of 2 seconds duration and a
172 transition on the <code class="property">'width'</code> property of 1
173 second duration.
175 </div>
177 <!-- ======================================================================================================= -->
178 <h3>
179 The <code class="property">'transition-property'</code> Property
180 </h3>
181 <p>
182 The <code class="property">'transition-property'</code> property specifies the name of the CSS property to which the transition is applied.
183 </p>
184 <div class="issue">
185 We may ultimately want to support a keypath syntax for this property. A keypath syntax would enable different transitions to be specified for components of a property. For example the blur of a shadow could have a different transition than the color of a shadow.
186 </div>
187 <table class="propdef">
188 <tbody>
189 <tr>
190 <td>
191 <em>Name:</em>
192 </td>
193 <td>
194 <dfn id="transition-property">transition-property</dfn>
195 </td>
196 </tr>
197 <tr>
198 <td>
199 <em>Value:</em>
200 </td>
201 <td>
202 none | [ all | <IDENT> ] [ ',' [ all | <IDENT> ] ]*
203 </td>
204 </tr>
205 <tr>
206 <td>
207 <em>Initial:</em>
208 </td>
209 <td>
210 all
211 </td>
212 </tr>
213 <tr>
214 <td>
215 <em>Applies to:</em>
216 </td>
217 <td>
218 all elements, :before and :after pseudo elements
219 </td>
220 </tr>
221 <tr>
222 <td>
223 <em>Inherited:</em>
224 </td>
225 <td>
226 no
227 </td>
228 </tr>
229 <tr>
230 <td>
231 <em>Percentages:</em>
232 </td>
233 <td>
234 N/A
235 </td>
236 </tr>
237 <tr>
238 <td>
239 <em>Media:</em>
240 </td>
241 <td>
242 visual
243 </td>
244 </tr>
245 <tr>
246 <td>
247 <em>Computed value:</em>
248 </td>
249 <td>
250 Same as specified value.
251 </td>
252 </tr>
253 </tbody>
254 </table>
256 <p>
257 A value of 'none' means that no property will transition.
258 Otherwise, a list of properties to be transitioned, or the
259 keyword 'all' which indicates that all properties are to be
260 transitioned, is given.
261 </p>
263 <p>
264 If one of the identifiers listed is not a recognized property
265 name or is not an animatable property, the implementation must
266 still start transitions on the animatable properties in the
267 list using the duration, delay, and timing function at their
268 respective indices in the lists for 'transition-duration',
269 'transition-delay', and 'transition-timing-function'. In other
270 words, unrecognized or non-animatable properties must be kept in
271 the list to preserve the matching of indices.
272 </p>
273 <p class="issue">
274 Are 'none', 'inherit', and 'initial' allowed as items in
275 a list of identifiers (of length greater than one)?
276 </p>
277 <p>
278 For the keyword 'all', or if one of the identifiers listed is a
279 shorthand property, implementations must start transitions for
280 any of its longhand sub-properties that are animatable (or, for
281 'all', all animatable properties), using the duration, delay,
282 and timing function at the index corresponding to the shorthand.
283 </p>
284 <p>
285 If a property is specified multiple times in the value of
286 'transition-property' (either on its own, via a shorthand that
287 contains it, or via the 'all' value), then the transition that
288 starts uses the duration, delay, and timing function at the
289 index corresponding to the <em>last</em> item in the value of
290 'transition-property' that calls for animating that property.
291 </p>
292 <p class="note">
293 Note: The <code class="property">all</code> value and shorthand
294 properties work in similar ways, so the <code
295 class="property">all</code> value is just like a shorthand that
296 covers all properties.
297 </p>
299 <!-- ======================================================================================================= -->
300 <h3>
301 The <code class="property">'transition-duration'</code> Property
302 </h3>
303 <p>
304 The <code class="property">'transition-duration'</code> property defines the length of time that a transition takes.
305 </p>
306 <table class="propdef">
307 <tbody>
308 <tr>
309 <td>
310 <em>Name:</em>
311 </td>
312 <td>
313 <dfn id="transition-duration">transition-duration</dfn>
314 </td>
315 </tr>
316 <tr>
317 <td>
318 <em>Value:</em>
319 </td>
320 <td>
321 <time> [, <time>]*
322 </td>
323 </tr>
324 <tr>
325 <td>
326 <em>Initial:</em>
327 </td>
328 <td>
329 0s
330 </td>
331 </tr>
332 <tr>
333 <td>
334 <em>Applies to:</em>
335 </td>
336 <td>
337 all elements, :before and :after pseudo elements
338 </td>
339 </tr>
340 <tr>
341 <td>
342 <em>Inherited:</em>
343 </td>
344 <td>
345 no
346 </td>
347 </tr>
348 <tr>
349 <td>
350 <em>Percentages:</em>
351 </td>
352 <td>
353 N/A
354 </td>
355 </tr>
356 <tr>
357 <td>
358 <em>Media:</em>
359 </td>
360 <td>
361 interactive
362 </td>
363 </tr>
364 <tr>
365 <td>
366 <em>Computed value:</em>
367 </td>
368 <td>
369 Same as specified value.
370 </td>
371 </tr>
372 </tbody>
373 </table>
374 <p>
375 This property specifies how long the transition from the old value to the new value should take. By default the value is '0s', meaning that the transition is immediate (i.e. there will be no animation). A negative value for <code class="property">transition-duration</code> is treated as '0s'.
376 </p>
378 <!-- =======================================================================================================
379 -->
381 <h3 id="transition-timing-function_tag">
382 The <code class="property">'transition-timing-function'</code> Property
383 </h3>
384 <p>
385 The <code class="property">'transition-timing-function'</code> property
386 describes how the intermediate values used during a transition will be
387 calculated. It allows for a transition to change speed over its
388 duration. These effects are commonly called <em>easing</em> functions.
389 In either case, a mathematical function that provides a smooth curve is
390 used.
391 </p>
392 <p>
393 Timing functions are either defined as a stepping function or
394 a <a
395 href="http://en.wikipedia.org/wiki/B%C3%A9zier_curve#Cubic_B.C3.A9zier_curves">cubic
396 Bézier curve</a>.
397 The timing function takes as its input the current elapsed percentage of
398 the transition duration and outputs a percentage that determines how
399 close the transition is to its goal state.
400 </p>
401 <p>
402 A <a href="http://en.wikipedia.org/wiki/Step_function">stepping</a>
403 function is defined by a number that divides the domain of operation
404 into equally sized intervals. Each subsequent interval is a equal step
405 closer to the goal state. The function also specifies whether the
406 change in output percentage happens at the start or end of the
407 interval (in other words, if 0% on the input percentage is the point
408 of initial change).
409 </p>
410 <div class="figure">
411 <img src="step.png" alt="The step timing function splits
412 the function domain into a number of disjoint straight line
413 segments. steps(1, start) is a function whose
414 output value is 1 for all input values. steps(1, end) is a function whose
415 output value is 0 for all input values less than 1, and output
416 is 1 for the input value of 1. steps(3, start) is a function that
417 divides the input domain into three segments, each 1/3 in length,
418 and 1/3 above the previous segment, with the first segment starting
419 at 1/3. steps(3, end) is a function that
420 divides the input domain into three segments, each 1/3 in length,
421 and 1/3 above the previous segment, with the first segment starting
422 at 0.">
423 </div>
424 <p class="caption">
425 Step timing functions
426 </p>
427 <p>
428 A <a
429 href="http://en.wikipedia.org/wiki/B%C3%A9zier_curve#Cubic_B.C3.A9zier_curves">cubic
430 Bézier curve</a> is defined by four control points, P<sub>0</sub>
431 through P<sub>3</sub> (see Figure 1). P<sub>0</sub> and P<sub>3</sub>
432 are always set to (0,0) and (1,1). The <code class="property">'transition-timing-function'</code> property is used
433 to specify the values for points P<sub>1</sub> and P<sub>2</sub>. These
434 can be set to preset values using the keywords listed below, or can be
435 set to specific values using the <code class="css">'cubic-bezier'</code> function.
436 In the <code class="css">'cubic-bezier'</code> function, P<sub>1</sub> and
437 P<sub>2</sub> are each specified by both an X and Y value.
438 </p>
439 <div class="figure">
440 <img src="TimingFunction.png" alt="The Bézier timing function is a
441 smooth curve from point P0 = (0,0) to point P3 = (1,1). The
442 length and orientation of the line segment P0-P1 determines
443 the tangent and the curvature of the curve at P0 and the
444 line segment P2-P3 does the same at P3.">
445 </div>
446 <p class="caption">
447 Bézier Timing Function Control Points
448 </p>
449 <table class="propdef">
450 <tbody>
451 <tr>
452 <td>
453 <em>Name:</em>
454 </td>
455 <td>
456 <dfn id="transition-timing-function">transition-timing-function</dfn>
457 </td>
458 </tr>
459 <tr>
460 <td>
461 <em>Value:</em>
462 </td>
463 <td>
464 ease | linear | ease-in | ease-out | ease-in-out | step-start | step-end | steps(<integer>[, [ start | end ] ]?) | cubic-bezier(<number>, <number>, <number>, <number>) [, [ ease | linear | ease-in | ease-out | ease-in-out | step-start | step-end | steps(<number>[, [ start | end ] ]?) | cubic-bezier(<number>, <number>, <number>, <number>) ] ]*
465 </td>
466 </tr>
467 <tr>
468 <td>
469 <em>Initial:</em>
470 </td>
471 <td>
472 ease
473 </td>
474 </tr>
475 <tr>
476 <td>
477 <em>Applies to:</em>
478 </td>
479 <td>
480 all elements, :before and :after pseudo elements
481 </td>
482 </tr>
483 <tr>
484 <td>
485 <em>Inherited:</em>
486 </td>
487 <td>
488 no
489 </td>
490 </tr>
491 <tr>
492 <td>
493 <em>Percentages:</em>
494 </td>
495 <td>
496 N/A
497 </td>
498 </tr>
499 <tr>
500 <td>
501 <em>Media:</em>
502 </td>
503 <td>
504 interactive
505 </td>
506 </tr>
507 <tr>
508 <td>
509 <em>Computed value:</em>
510 </td>
511 <td>
512 Same as specified value.
513 </td>
514 </tr>
515 </tbody>
516 </table>
517 <p>
518 The timing functions have the following definitions.
519 </p>
520 <dl>
521 <dt>
522 ease
523 </dt>
524 <dd>
525 The ease function is equivalent to cubic-bezier(0.25, 0.1, 0.25, 1.0).
526 </dd>
527 <dt>
528 linear
529 </dt>
530 <dd>
531 The linear function is equivalent to cubic-bezier(0.0, 0.0, 1.0, 1.0).
532 </dd>
533 <dt>
534 ease-in
535 </dt>
536 <dd>
537 The ease-in function is equivalent to cubic-bezier(0.42, 0, 1.0, 1.0).
538 </dd>
539 <dt>
540 ease-out
541 </dt>
542 <dd>
543 The ease-out function is equivalent to cubic-bezier(0, 0, 0.58, 1.0).
544 </dd>
545 <dt>
546 ease-in-out
547 </dt>
548 <dd>
549 The ease-in-out function is equivalent to cubic-bezier(0.42, 0, 0.58, 1.0)
550 </dd>
551 <dt>
552 step-start
553 </dt>
554 <dd>
555 The step-start function is equivalent to steps(1, start).
556 </dd>
557 <dt>
558 step-end
559 </dt>
560 <dd>
561 The step-end function is equivalent to steps(1, end).
562 </dd>
563 <dt>
564 steps
565 </dt>
566 <dd>
567 Specifies a stepping function, described above, taking two
568 parameters. The first parameter specifies the number of intervals
569 in the function. It must be a positive integer (greater than 0).
570 The second parameter, which is optional, is
571 either the value 'start' or 'end', and specifies the point
572 at which the change of values occur within the interval.
573 If the second parameter is omitted, it is given the value 'end'.
574 </dd>
575 <dt>
576 cubic-bezier
577 </dt>
578 <dd>
579 Specifies a <a
580 href="http://en.wikipedia.org/wiki/B%C3%A9zier_curve">cubic-bezier
581 curve</a>. The four values specify points P<sub>1</sub> and
582 P<sub>2</sub> of the curve as (x1, y1, x2, y2). Both x values must be
583 in the range [0, 1] or the definition is invalid. The y values can
584 exceed this range.
585 </dd>
586 </dl><!-- ======================================================================================================= -->
587 <h3>
588 The <code class="property">'transition-delay'</code> Property
589 </h3>
590 <p>
591 The <code class="property">'transition-delay'</code> property defines when the transition will start. It allows a transition to begin execution some some period of time from when it is applied. A <code class="property">'transition-delay'</code> value of '0s' means the transition will execute as soon as the property is changed. Otherwise, the value specifies an offset from the moment the property is changed, and the transition will delay execution by that offset.
592 </p>
593 <p>
594 If the value for <code class="property">'transition-delay'</code> is a negative time offset then the transition will execute the moment the property is changed, but will appear to have begun execution at the specified offset. That is, the transition will appear to begin part-way through its play cycle. In the case where a transition has implied starting values and a negative <code class="property">'transition-delay'</code>, the starting values are taken from the moment the property is changed.
595 </p>
596 <table class="propdef">
597 <tbody>
598 <tr>
599 <td>
600 <em>Name:</em>
601 </td>
602 <td>
603 <dfn id="transition-delay">transition-delay</dfn>
604 </td>
605 </tr>
606 <tr>
607 <td>
608 <em>Value:</em>
609 </td>
610 <td>
611 <time> [, <time>]*
612 </td>
613 </tr>
614 <tr>
615 <td>
616 <em>Initial:</em>
617 </td>
618 <td>
619 0s
620 </td>
621 </tr>
622 <tr>
623 <td>
624 <em>Applies to:</em>
625 </td>
626 <td>
627 all elements, :before and :after pseudo elements
628 </td>
629 </tr>
630 <tr>
631 <td>
632 <em>Inherited:</em>
633 </td>
634 <td>
635 no
636 </td>
637 </tr>
638 <tr>
639 <td>
640 <em>Percentages:</em>
641 </td>
642 <td>
643 N/A
644 </td>
645 </tr>
646 <tr>
647 <td>
648 <em>Media:</em>
649 </td>
650 <td>
651 interactive
652 </td>
653 </tr>
654 <tr>
655 <td>
656 <em>Computed value:</em>
657 </td>
658 <td>
659 Same as specified value.
660 </td>
661 </tr>
662 </tbody>
663 </table><!-- ======================================================================================================= -->
664 <h3>
665 The <code class="property">'transition'</code> Shorthand Property
666 </h3>
667 <p>
668 The <code class="property">'transition'</code> shorthand property combines the four properties described above into a single property.
669 </p>
670 <p>
671 Note that order is important in this property. The first value that can be
672 parsed as a time is assigned to the transition-duration. The second value that
673 can be parsed as a time is assigned to transition-delay.
674 </p>
675 <p class="issue">
676 An alternative proposal is to accept the font shorthand approach of
677 using a "/" character between the values of the same type. e.g. 2s/4s would
678 mean a duration of 2 seconds and a delay of 4 seconds.
679 </p>
680 <table class="propdef">
681 <tbody>
682 <tr>
683 <td>
684 <em>Name:</em>
685 </td>
686 <td>
687 <dfn id="transition">transition</dfn>
688 </td>
689 </tr>
690 <tr>
691 <td>
692 <em>Value:</em>
693 </td>
694 <td>
695 [<'transition-property'> || <'transition-duration'> || <'transition-timing-function'> || <'transition-delay'> [, [<'transition-property'> || <'transition-duration'> || <'transition-timing-function'> || <'transition-delay'>]]*
696 </td>
697 </tr>
698 <tr>
699 <td>
700 <em>Initial:</em>
701 </td>
702 <td>
703 see individual properties
704 </td>
705 </tr>
706 <tr>
707 <td>
708 <em>Applies to:</em>
709 </td>
710 <td>
711 all elements, :before and :after pseudo elements
712 </td>
713 </tr>
714 <tr>
715 <td>
716 <em>Inherited:</em>
717 </td>
718 <td>
719 no
720 </td>
721 </tr>
722 <tr>
723 <td>
724 <em>Percentages:</em>
725 </td>
726 <td>
727 N/A
728 </td>
729 </tr>
730 <tr>
731 <td>
732 <em>Media:</em>
733 </td>
734 <td>
735 interactive
736 </td>
737 </tr>
738 <tr>
739 <td>
740 <em>Computed value:</em>
741 </td>
742 <td>
743 Same as specified value.
744 </td>
745 </tr>
746 </tbody>
747 </table>
749 <h2 id="starting">
750 Starting of transitions
751 </h2>
753 <p>
754 When the computed value of an animatable property changes,
755 implementations must decide what transitions to start based on
756 the values of the 'transition-property', 'transition-duration',
757 'transition-timing-function', and 'transition-delay' properties
758 at the time the animatable property would first have its new
759 computed value.
760 </p>
761 <div class="example" id="manual-reversing-example">
762 <p style="display:none">
763 Example(s):
764 </p>
765 <p>This provides a way for authors to specify different values
766 of the 'transition-*' properties for the “forward”
767 and “reverse” transitions (but see <a
768 href="#reversing">below</a> for special reversing behavior when
769 an <em>incomplete</em> transition is interrupted). Authors can
770 specify the value of 'transition-duration',
771 'transition-timing-function', or 'transition-delay' in the same
772 rule where they specify the value that triggers the transition,
773 or can change these properties at the same time as they change
774 the property that triggers the transition. Since it's the new
775 values of these 'transition-*' properties that affect the
776 transition, these values will be used for the transitions
777 <em>to</em> the associated transitioning values. For example:
778 </p>
779 <pre>li {
780 transition: background-color linear 1s;
781 background: blue;
782 }
783 li:hover {
784 background-color: green;
785 transition-duration: 2s; /* applies to the transition *to* the :hover state */
786 }</pre>
787 <p>
788 When a list item with these style rules enters the :hover
789 state, the computed 'transition-duration' at the time that
790 'background-color' would have its new value ('green') is '2s',
791 so the transition from 'blue' to 'green' takes 2 seconds.
792 However, when the list item leaves the :hover state, the
793 transition from 'green' to 'blue' takes 1 second.
794 </p>
795 </div>
797 <p>
798 When the computed value of a property changes, implementations
799 must start transitions based on the relevant item (see <a
800 href="#transition-property">the definition of
801 'transition-property'</a>) in the computed value of
802 'transition-property'. Corresponding to this item there are
803 values of 'transition-duration' and 'transition-delay' (see <a
804 href="#list-matching">the rules on matching lists</a>). Define
805 the <dfn>combined duration</dfn> of the transition as the sum of
806 max('transition-duration', '0s') and 'transition-delay'. When
807 the combined duration is greater than '0s', then a transition
808 starts based on the values of 'transition-duration',
809 'transition-delay', and 'transition-timing-function'; in other
810 cases transitions do not occur.
811 </p>
813 <p>
814 Since this specification does not define
815 when computed values change, and thus what changes to
816 computed values are considered simultaneous,
817 authors should be aware that changing any of the transition
818 properties a small amount of time after making a change that
819 might transition can result in behavior that varies between
820 implementations, since the changes might be considered
821 simultaneous in some implementations but not others.
822 </p>
823 <p class="note">Say something about simultaneity</p>
825 <p>
826 Once the transition of a property has started, it must continue
827 running based on the original timing function, duration, and
828 delay, even if the 'transition-timing-function',
829 'transition-duration', or 'transition-delay' property changes
830 before the transition is complete. However, if the
831 'transition-property' property changes such that the transition
832 would not have started, the transition must stop (and the
833 property must immediately change to its final value).
834 </p>
836 <p>
837 Implementations must not start a transition when the computed
838 value of a property changes as a result of declarative animation
839 (as opposed to scripted animation).
840 </p>
842 <p>
843 Implementations also must not start a transition when the
844 computed value changes because it is inherited (directly or
845 indirectly) from another element that is transitioning the same
846 property.
847 </p>
849 <h2 id="reversing">
850 Automatically reversing interrupted transitions
851 </h2>
852 <p>
853 A common type of transition effect is when a running transition is
854 interrupted and the property is reset to its original value. An
855 example is a hover effect on an element, where the pointer enters and
856 exits the element before the effect has completed. If the outgoing and
857 incoming transitions are executed using their specified durations and
858 timing functions, the resulting effect can be distractingly
859 asymmetric. Instead, the expected behavior is that the new transition
860 should be the reverse of what has already executed.
861 </p>
863 <p>
864 If a running transition with duration T, executing so far for duration TE,
865 from state A, to state B, is interrupted by
866 a property change that would start a new transition back to state A, and
867 all the transition attributes are the same (duration, delay and timing function),
868 then the new transition must reverse the effect. The new transition must:
869 </p>
871 <ol>
872 <li>
873 Use the B and A states as its "from" and "to" states respectively. It
874 does not use the current value as its from state, due to the rules below.
875 </li>
876 <li>
877 Execute with the same duration T, but starting as if the transition had
878 already begun, without any transition delay, at the moment which would
879 cause the new transition to finish in TE from the moment of interruption. In other
880 words, the new transition will execute as if it started T-TE in the past.
881 </li>
882 <li>
883 Use a timing function that is the portion of the curve traversed up
884 to the moment of interruption, followed in the opposite direction (towards
885 the starting point). This will make the transition appear as if it
886 is playing backwards.
887 </li>
888 <li>
889 Ignore any transition delay.
890 </li>
891 </ol>
893 <p>
894 For example, suppose there is a transition with a duration of two
895 seconds. If this transition is interrupted after 0.5 seconds and the
896 property value assigned to the original value, then the new transition
897 effect will be the reverse of the original, as if it had begun
898 1.5 seconds in the past.
899 </p>
901 <p>
902 Note that by using the defined from and to states for the reversing
903 transition, it is also possible that it may reverse again, if
904 interrupted; for example, if the transition reversing to state A was
905 again interrupted by a property change to state B.
906 </p>
908 <p class="issue">Issue:
909 This introduces the concept of reversing a timing function,
910 which the spec has otherwise resisted doing, and also introduces
911 a discontinuity between transitions that have
912 almost completed (which get automatically reversed and thus have
913 their timing function reversed) and transitions that have fully
914 completed (where the reversal doesn't lead to the timing
915 function being reversed). An alternative proposal that avoids
916 this is to follow the normal timing function algorithm, except
917 multiply the duration (and also shorten any negative delay) by
918 the (output) value of the transition timing function of the
919 incomplete transition at the time it was interrupted, and, to
920 account for multiple reverses in sequence, to divide by the
921 shortening applied to the transition being interrupted. For
922 more details see this thread:
923 <a href="http://lists.w3.org/Archives/Public/www-style/2009Nov/thread.html#msg302">November 2009 part</a>,
924 <a href="http://lists.w3.org/Archives/Public/www-style/2009Dec/thread.html#msg319">December 2009 part</a>,
925 <a href="http://lists.w3.org/Archives/Public/www-style/2010Jan/thread.html#msg136">January 2010 part</a>.
926 </p>
928 <h2>
929 Transition Events
930 </h2>
931 <p>
932 The completion of a CSS Transition generates a corresponding <a href="http://www.w3.org/TR/DOM-Level-2-Events/events.html">DOM Event</a>.
933 An event is fired for each property that undergoes a transition.
934 This allows a content developer to perform actions that synchronize
935 with the completion of a transition.
936 </p>
937 <p>
938 Each event provides the name of the property the transition is
939 associated with as well as the duration of the transition.
940 </p>
941 <dl>
942 <dt>
943 <b>Interface <i><a id="Events-TransitionEvent" name='Events-TransitionEvent'>TransitionEvent</a></i></b>
944 </dt>
945 <dd>
946 <p>
947 The <code>TransitionEvent</code> interface provides specific contextual information associated with transitions.
948 </p>
949 <dl>
950 <dt>
951 <b>IDL Definition</b>
952 </dt>
953 <dd>
954 <div class='idl-code'>
955 <pre>
956 interface TransitionEvent : Event {
957 readonly attribute DOMString propertyName;
958 readonly attribute float elapsedTime;
959 readonly attribute DOMString pseudoElement;
960 void initTransitionEvent(in DOMString typeArg,
961 in boolean canBubbleArg,
962 in boolean cancelableArg,
963 in DOMString propertyNameArg,
964 in float elapsedTimeArg,
965 in DOMString pseudoElementArg);
966 };
967 </pre>
968 </div>
969 </dd>
970 <dt>
971 <b>Attributes</b>
972 </dt>
973 <dd>
974 <dl>
975 <dt>
976 <code class='attribute-name'><a id="Events-TransitionEvent-propertyName" name='Events-TransitionEvent-propertyName'>propertyName</a></code> of type <code>DOMString</code>, readonly
977 </dt>
978 <dd>
979 The name of the CSS property associated with the transition.
980 </dd>
981 </dl>
982 <dl>
983 <dt>
984 <code class='attribute-name'><a id="Events-TransitionEvent-elapsedTime" name='Events-TransitionEvent-elapsedTime'>elapsedTime</a></code> of type <code>float</code>, readonly
985 </dt>
986 <dd>
987 The amount of time the transition has been running, in seconds, when this event fired. Note that this value is not affected by the value of <code class="property">transition-delay</code>.
988 </dd>
989 </dl>
990 <dl>
991 <dt>
992 <code class='attribute-name'><a id="Events-TransitionEvent-pseudoElement" name='Events-TransitionEvent-pseudoElement'>pseudoElement</a></code> of type <code>DOMString</code>, readonly
993 </dt>
994 <dd>
995 The name (beginning with two colons) of the CSS
996 pseudo-element on which the transition occured (in
997 which case the target of the event is that
998 pseudo-element's corresponding element), or the empty
999 string if the transition occurred on an element (which
1000 means the target of the event is that element).
1001 </dd>
1002 </dl>
1003 </dd>
1004 <dt>
1005 <b>Methods</b>
1006 </dt>
1007 <dd>
1008 <dl>
1009 <dt>
1010 <code class='method-name'><a id="Events-TransitionEvent-initTransitionEvent" name='Events-TransitionEvent-initTransitionEvent'>initTransitionEvent</a></code>
1011 </dt>
1012 <dd>
1013 <div class='method'>
1014 The <code>initTransitionEvent</code> method is used to
1015 initialize the value of a <code>TransitionEvent</code>
1016 created through the <a
1017 href='http://www.w3.org/TR/DOM-Level-2-Events/events.html#Events-DocumentEvent'><code>DocumentEvent</code></a>
1018 interface. This method may only be called before the
1019 <code>TransitionEvent</code> has been dispatched via the
1020 <code>dispatchEvent</code> method, though it may be called
1021 multiple times during that phase if necessary. If called
1022 multiple times, the final invocation takes precedence.
1023 <p class="issue">Should new events being created still
1024 have init*Event methods?</p>
1025 <div class='parameters'>
1026 <b>Parameters</b>
1027 <div class='paramtable'>
1028 <dl>
1029 <dt>
1030 <code class='parameter-name'>typeArg</code> of type <code>DOMString</code>
1031 </dt>
1032 <dd>
1033 Specifies the event type.<br>
1034 </dd>
1035 <dt>
1036 <code class='parameter-name'>canBubbleArg</code> of type <code>boolean</code>
1037 </dt>
1038 <dd>
1039 Specifies whether or not the event can bubble.<br>
1040 </dd>
1041 <dt>
1042 <code class='parameter-name'>cancelableArg</code> of type <code>boolean</code>
1043 </dt>
1044 <dd>
1045 Specifies whether or not the event's default action can be prevented. Since a TransitionEvent
1046 is purely for notification, there is no default action.<br>
1047 </dd>
1048 <dt>
1049 <code class='parameter-name'>propertyNameArg</code> of type <code>DOMString</code>
1050 </dt>
1051 <dd>
1052 Specifies the name of the property associated with the <a href='http://www.w3.org/TR/DOM-Level-2-Events/events.html#Events-Event'><code>Event</code></a>.
1053 (See the <a href="#Events-TransitionEvent-propertyName">propertyName</a> attribute.)
1054 </dd>
1055 <dt>
1056 <code class='parameter-name'>elapsedTimeArg</code> of type <code>float</code>
1057 </dt>
1058 <dd>
1059 Specifies the amount of time, in seconds, the transition has been running at the time of initialization.
1060 (See the <a href="#Events-TransitionEvent-elapsedTime">elapsedTime</a> attribute.)
1061 </dd>
1062 <dt>
1063 <code class='parameter-name'>pseudoElementArg</code> of type <code>DOMString</code>
1064 </dt>
1065 <dd>
1066 Specifies the pseudo-element on which the
1067 transition occurred.
1068 (See the <a href="#Events-TransitionEvent-pseudoElement">pseudoElement</a> attribute.)
1069 <span class="issue">Does adding this additional argument create any compatibility problems?</span>
1070 </dd>
1071 </dl>
1072 </div>
1073 </div><!-- parameters -->
1074 <div>
1075 <b>No Return Value</b>
1076 </div>
1077 <div>
1078 <b>No Exceptions</b>
1079 </div>
1080 </div><!-- method -->
1081 </dd>
1082 </dl>
1083 </dd>
1084 </dl>
1085 </dd>
1086 </dl>
1087 <p>
1088 There is one type of transition event available.
1089 </p>
1090 <dl>
1091 <dt>
1092 <b>transitionend</b>
1093 </dt>
1094 <dd>
1095 The 'transitionend' event occurs at the completion of the transition. In the
1096 case where a transition is removed before completion, such as if the
1097 transition-property is removed, then the event will not fire.
1098 <ul>
1099 <li>Bubbles: Yes
1100 </li>
1101 <li>Cancelable: Yes
1102 </li>
1103 <li>Context Info: propertyName, elapsedTime
1104 </li>
1105 </ul>
1106 </dd>
1107 </dl>
1109 <h2 id="animation-of-property-types-">
1110 Animation of property types
1111 </h2>
1113 <p>
1114 The following describes how each property type undergoes transition or
1115 animation.
1116 </p>
1118 <ul>
1119 <li>
1120 <strong>color</strong>: interpolated via red, green, blue and alpha
1121 components (treating each as a number, see below).
1122 <div class="issue">Issue: Are the colors interpolated in
1123 premultiplied space or non-premultiplied space?</div>
1124 </li>
1125 <li>
1126 <strong>length</strong>: interpolated as real numbers.
1127 </li>
1128 <li>
1129 <strong>percentage</strong>: interpolated as real numbers.
1130 </li>
1131 <li>
1132 <strong>integer</strong>: interpolated via discrete steps (whole
1133 numbers). The interpolation happens in real number space and is
1134 converted to an integer using <code>floor()</code>.
1135 <span class="issue">
1136 This floor behavior is inconsistent with SMIL Animation /
1137 SVG Animation.
1138 </span>
1139 </li>
1140 <li>
1141 <strong>font weight</strong>: interpolated via discrete steps
1142 (multiples of 100). The interpolation happens in real number
1143 space and is converted to an integer by rounding to the
1144 nearest multiple of 100.
1145 <span class="issue">
1146 This round-to-nearest behavior is inconsistent with the
1147 floor behavior used for integer types, but probably should
1148 be consistent (one way or the other).
1149 </span>
1150 </li>
1151 <li>
1152 <strong>number</strong>: interpolated as real (floating point)
1153 numbers.
1154 </li>
1155 <li>
1156 <strong>transform list</strong>: see
1157 CSS Transforms specification [[!CSS3-TRANSFORMS]].
1158 </li>
1159 <li>
1160 <strong>rectangle</strong>: interpolated via the x, y,
1161 width and height components (treating each as a number).
1162 </li>
1163 <li>
1164 <strong>visibility</strong>: if one of the values is
1165 'visible', interpolated as a discrete step where values of the
1166 timing function between 0 and 1 map to 'visible' and other
1167 values of the timing function (which occur only at the
1168 start/end of the transition or as a result of 'cubic-bezier()'
1169 functions with Y values outside of [0, 1]) map to the closer
1170 endpoint; if neither value is 'visible' then not interpolable.
1171 </span>
1172 </li>
1173 <li>
1174 <strong>shadow</strong>: interpolated via the color, x, y
1175 and blur components (treating them as color and numbers where
1176 appropriate). In the case where there are lists of shadows,
1177 the shorter list is padded at the end with shadows whose
1178 color is transparent and all lengths (x, y, blur) are 0.
1179 </li>
1180 <li>
1181 <strong>gradient</strong>: interpolated via the
1182 positions and colors of each stop. They must have the same type
1183 (radial or linear) and same number of stops in order to be animated.
1184 <span class="note">Note: [[CSS3-IMAGES]] may extend this
1185 definition.</span>
1186 </li>
1187 <li>
1188 <strong>paint server</strong> (SVG): interpolation is only supported
1189 between</strong>: gradient to gradient and color to color. They then
1190 work as above.
1191 </li>
1192 <li>
1193 <strong>list of above types</strong>: If the lists have the
1194 same number of items, each item in the list is interpolated using the
1195 rules above. Otherwise the interpolation is determined by the property
1196 rules. If the property extends its list by repeating values, then this
1197 repeated form will be used in the interpolation (<code class="property">'background-position'</code>
1198 is an example of a property that would transition between lists of different lengths). If
1199 the property does not allow extending its list, then no interpolation
1200 will occur.
1201 </li>
1202 <li>
1203 <strong>a shorthand property</strong>: If any part of a
1204 shorthand can be animated, then interpolation is performed as
1205 if those animatable properties were individually specified.
1206 </li>
1207 </ul>
1209 <p class="issue">Issue: Need to describe handling of out-of-range
1210 values that can result from cubic-bezier(). Clamping values to the
1211 allowed range is probably the best solution.</p>
1213 <h2>
1214 Animatable properties
1215 </h2>
1217 <!--
1218 As resolved in
1219 http://lists.w3.org/Archives/Public/www-style/2011Sep/0497.html
1220 -->
1221 <p>For properties that exist at the time this specification was
1222 developed, this specification defines whether and how they are
1223 animated. However, future CSS specifications may define
1224 additional properties, additional values for existing properties,
1225 or additional animation behavior of existing values. In order to
1226 describe new animation behaviors and to have the definition of
1227 animation behavior in a more appropriate location, future CSS
1228 specifications should include an "Animatable:" line in the summary
1229 of the property's definition (in addition to the other lines
1230 described in [[CSS21]], <a
1231 href="http://www.w3.org/TR/CSS21/about.html#property-defs">section
1232 1.4.2</a>). This line should say "no" to indicate that a property
1233 cannot be animated or should reference an animation behavior
1234 (which may be one of the behaviors in the <a
1235 href="#animation-of-property-types-">Animation of property
1236 types</a> section above, or may be a new behavior) to define how
1237 the property animates. Such definitions override those given in
1238 this specification.</p>
1240 <h3>
1241 Properties from CSS
1242 </h3>
1244 <table class="animatable-properties">
1245 <tr>
1246 <th>Property Name</th>
1247 <th>Type</th>
1248 </tr>
1249 <tr>
1250 <td>background-color</td><td>color</tr>
1251 <tr>
1252 <td>background-position</td><td>percentage, length</td>
1253 </tr>
1254 <tr>
1255 <td>border-bottom-color</td><td>color</td>
1256 </tr>
1257 <tr>
1258 <td>border-bottom-width</td><td>length</td>
1259 </tr>
1260 <tr>
1261 <td>border-left-color</td><td>color</td>
1262 </tr>
1263 <tr>
1264 <td>border-left-width</td><td>length</td>
1265 </tr>
1266 <tr>
1267 <td>border-right-color</td><td>color</td>
1268 </tr>
1269 <tr>
1270 <td>border-right-width</td><td>length</td>
1271 </tr>
1272 <tr>
1273 <td>border-spacing</td><td>length</td>
1274 </tr>
1275 <tr>
1276 <td>border-top-color</td><td>color</td>
1277 </tr>
1278 <tr>
1279 <td>border-top-width</td><td>length</td>
1280 </tr>
1281 <tr>
1282 <td>bottom</td><td>length, percentage</td>
1283 </tr>
1284 <tr>
1285 <td>clip</td><td>rectangle</td>
1286 </tr>
1287 <tr>
1288 <td>color</td><td>color</td>
1289 </tr>
1290 <tr>
1291 <td>crop <span class="issue">css3-content will likely advance slower than this specification, in which case this definition should move there</span></td><td>rectangle</td>
1292 </tr>
1293 <tr>
1294 <td>font-size</td><td>length, percentage</td>
1295 </tr>
1296 <tr>
1297 <td>font-weight</td><td>font weight</td>
1298 </tr>
1299 <tr>
1300 <td>height</td><td>length, percentage</td>
1301 </tr>
1302 <tr>
1303 <td>left</td><td>length, percentage</td>
1304 </tr>
1305 <tr>
1306 <td>letter-spacing</td><td>length</td>
1307 </tr>
1308 <tr>
1309 <td>line-height</td><td>number, length, percentage</td>
1310 </tr>
1311 <tr>
1312 <td>margin-bottom</td><td>length</td>
1313 </tr>
1314 <tr>
1315 <td>margin-left</td><td>length</td>
1316 </tr>
1317 <tr>
1318 <td>margin-right</td><td>length</td>
1319 </tr>
1320 <tr>
1321 <td>margin-top</td><td>length</td>
1322 </tr>
1323 <tr>
1324 <td>max-height</td><td>length, percentage</td>
1325 </tr>
1326 <tr>
1327 <td>max-width</td><td>length, percentage </td>
1328 </tr>
1329 <tr>
1330 <td>min-height</td><td>length, percentage</td>
1331 </tr>
1332 <tr>
1333 <td>min-width</td><td>length, percentage</td>
1334 </tr>
1335 <tr>
1336 <td>opacity</td><td>number</td>
1337 </tr>
1338 <tr>
1339 <td>outline-color</td><td>color</td>
1340 </tr>
1341 <tr>
1342 <td>outline-offset</td><td>integer</td>
1343 </tr>
1344 <tr>
1345 <td>outline-width</td><td>length</td>
1346 </tr>
1347 <tr>
1348 <td>padding-bottom</td><td>length</td>
1349 </tr>
1350 <tr>
1351 <td>padding-left</td><td>length</td>
1352 </tr>
1353 <tr>
1354 <td>padding-right</td><td>length</td>
1355 </tr>
1356 <tr>
1357 <td>padding-top</td><td>length</td>
1358 </tr>
1359 <tr>
1360 <td>right</td><td>length, percentage</td>
1361 </tr>
1362 <tr>
1363 <td>text-indent</td><td>length, percentage</td>
1364 </tr>
1365 <tr>
1366 <td>text-shadow</td><td>shadow</td>
1367 </tr>
1368 <tr>
1369 <td>top</td><td>length, percentage</td>
1370 </tr>
1371 <tr>
1372 <td>vertical-align</td><td>length, percentage</td>
1373 </tr>
1374 <tr>
1375 <td>visibility</td><td>visibility</td>
1376 </tr>
1377 <tr>
1378 <td>width</td><td>length, percentage</td>
1379 </tr>
1380 <tr>
1381 <td>word-spacing</td><td>length, percentage</td>
1382 </tr>
1383 <tr>
1384 <td>z-index</td><td>integer</td>
1385 </tr>
1386 </table>
1388 <p class="issue">
1389 This list omits the following properties that Gecko can animate, and
1390 which likely should be included:
1391 background-size,
1392 border-*-radius,
1393 box-shadow,
1394 column-count,
1395 column-gap,
1396 column-rule-color,
1397 column-rule-width,
1398 column-width,
1399 font-size-adjust,
1400 font-stretch,
1401 marker-offset,
1402 text-decoration-color,
1403 transform,
1404 transform-origin.
1405 </p>
1407 <h3>
1408 Properties from SVG
1409 </h3>
1411 <p>
1412 All properties defined as animatable in the SVG specification, provided
1413 they are one of the property types listed above.
1414 </p>
1416 <!-- <table>
1417 <tr>
1418 <th>Property Name</th><th>Type</th>
1419 </tr>
1420 <tr>
1421 <td>stop-color</td><td>color</td>
1422 </tr>
1423 <tr>
1424 <td>stop-opacity</td><td>float</td>
1425 </tr>
1426 <tr>
1427 <td>fill</td><td>paint server</td>
1428 </tr>
1429 <tr>
1430 <td>fill-opacity</td><td>float</td>
1431 </tr>
1432 <tr>
1433 <td>stroke</td><td>paint server</td>
1434 </tr>
1435 <tr>
1436 <td>stroke-dasharray</td><td>list of numbers</td>
1437 </tr>
1438 <tr>
1439 <td>stroke-dashoffset</td><td>number</td>
1440 </tr>
1441 <tr>
1442 <td>stroke-miterlimit</td><td>number</td>
1443 </tr>
1444 <tr>
1445 <td>stroke-opacity</td><td>float</td>
1446 </tr>
1447 <tr>
1448 <td>stroke-width</td><td>float</td>
1449 </tr>
1450 <tr>
1451 <td>viewport-fill</td><td>color</td>
1452 </tr>
1453 <tr>
1454 <td>viewport-fill-opacity</td><td>color</td>
1455 </tr>
1456 </table> -->
1459 <h2>References</h2>
1461 <h3 class="no-num">Normative references</h3>
1462 <!--normative-->
1464 <h3 class="no-num">Other references</h3>
1465 <!--informative-->
1469 <h2 class="no-num">Property index</h2>
1470 <!-- properties -->
1474 <h2 class="no-num" id="index">Index</h2>
1475 <!--index-->
1477 </body>
1478 </html>
1479 <!-- Keep this comment at the end of the file
1480 Local variables:
1481 mode: sgml
1482 sgml-default-doctype-name:"html"
1483 sgml-minimize-attributes:t
1484 End:
1485 -->