Wed, 03 Feb 2016 16:22:02 +1100
[css-transitions] Typo fix.
1 <h1>CSS Transitions</h1>
3 <style type="text/css">
4 table.animatable-properties {
5 border-collapse: collapse;
6 }
7 table.animatable-properties td {
8 padding: 0.2em 1em;
9 border: 1px solid black;
10 }
11 div.prod { margin: 1em 2em; }
12 </style>
15 <pre class="metadata">
16 Status: ED
17 Work Status: Refining
18 ED: https://drafts.csswg.org/css-transitions/
19 Shortname: css-transitions
20 Group: csswg
21 Level: 1
22 TR: https://www.w3.org/TR/css3-transitions/
23 Previous version: https://www.w3.org/TR/2013/WD-css3-transitions-20131119/
24 ED: https://drafts.csswg.org/css-transitions/
25 Editor: L. David Baron, Mozilla, http://dbaron.org/
26 Editor: Dean Jackson, Apple Inc, dino@apple.com
27 Editor: David Hyatt, Apple Inc, hyatt@apple.com
28 Editor: Chris Marrin, Apple Inc, cmarrin@apple.com
29 Issue Tracking: Bugzilla bugs for this level https://www.w3.org/Bugs/Public/buglist.cgi?query_format=advanced&product=CSS&component=Transitions&resolution=---&status_whiteboard=defer%20to%20level%202&status_whiteboard_type=notregexp
30 Issue Tracking: Bugzilla bugs for all levels https://www.w3.org/Bugs/Public/buglist.cgi?query_format=advanced&product=CSS&component=Transitions&resolution=---
31 Abstract: CSS Transitions allows property changes in CSS values to occur smoothly over a specified duration.
32 Status Text: <strong>This document</strong> is expected to be relatively close to last call. While some issues raised have yet to be addressed, new features are extremely unlikely to be considered for this level. <p>The following behaviors are at risk: <ul><li><a href="#discrete-interpolation-at-risk">Interpolation in steps of property types that cannot be interpolated</a></li></ul>
33 Ignored Terms: float
34 Ignored Vars: x1, x2, y1, y2
35 Link Defaults: css-transforms (property) transform
36 </pre>
37 <!-- FIXME: font-size and font-weight link defaults don't work -->
38 <pre class="link-defaults">
39 spec:css21; type:property;
40 text:top
41 text:right
42 text:bottom
43 text:left
44 text:margin-top
45 text:margin-right
46 text:margin-bottom
47 text:margin-left
48 text:padding-top
49 text:padding-right
50 text:padding-bottom
51 text:padding-left
52 text:border-top-color
53 text:border-right-color
54 text:border-bottom-color
55 text:border-left-color
56 text:border-top-width
57 text:border-right-width
58 text:border-bottom-width
59 text:border-left-width
60 text:background-color
61 text:background-position
62 text:border-spacing
63 text:width
64 text:height
65 text:min-width
66 text:min-height
67 text:max-width
68 text:max-height
69 text:clip
70 text:letter-spacing
71 text:line-height
72 text:outline-color
73 text:outline-width
74 text:text-indent
75 text:font-size
76 text:font-weight
77 text:vertical-align
78 text:visibility
79 text:word-spacing
80 text:z-index
81 spec:css-color-3;
82 type:property;
83 text:color
84 text:opacity
85 type:value
86 text:green
87 text:blue
88 text:transparent
89 spec:css-values-3; type:type; text:<time>
90 </pre>
91 <!-- FIXME: These overrides aren't great for dev/TR switching -->
92 <pre class="anchors">
93 url: https://drafts.csswg.org/css-backgrounds-3/#shadow-inset; type: value; for: shadow; text: inset;
94 url: https://www.w3.org/TR/CSS21/visufx.html#propdef-visibility; type: value; for: visibility; text: visible;
95 urlPrefix: https://drafts.csswg.org/css-color-3/; type: value;
96 text: transparent
97 text: blue
98 text: green
99 url: http://w3c.github.io/dom/#constructing-events; type: dfn; text: event constructor;
100 url: https://html.spec.whatwg.org/multipage/infrastructure.html#concept-event-dispatch; type: dfn; text: dispatch;
101 </pre>
102 </dl>
104 <h2 id="introduction">Introduction</h2>
106 <p><em>This section is not normative.</em>
107 <p>
108 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.
109 </p>
111 <h2 id="transitions"><span id="transitions-">Transitions</span></h2>
112 <p>
113 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.
114 </p>
115 <p>
116 For example, suppose that transitions of one second have been defined on the 'left' and
117 'background-color' 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.
118 </p>
119 <div class="figure">
120 <img src="transition1.png" alt="">
121 </div>
122 <p class="caption">
123 Transitions of 'left' and 'background-color'
124 </p>
125 <p>
126 Transitions are a presentational effect. The <a>computed value</a> of a property transitions over time from the old value to the new value. Therefore if a script queries the <a>computed value</a> of a property (or other data depending on it) as it is transitioning, it will see an intermediate value that represents the current animated value of the property.
127 </p>
128 <p>
129 Only animatable CSS properties can be transitioned. See the table at the end of this document for a list
130 of properties that are animatable.
131 </p>
132 <p>
133 The transition for a property is defined using a number of new properties. For example:
134 </p>
135 <div class="example">
136 <p style="display:none">
137 Example(s):
138 </p>
139 <pre>
140 div {
141 transition-property: opacity;
142 transition-duration: 2s;
143 }
144 </pre>The above example defines a transition on the 'opacity' 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.
145 </div>
146 <p>
147 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:
148 </p>
149 <div class="example">
150 <p style="display:none">
151 Example(s):
152 </p>
153 <pre>
154 div {
155 transition-property: opacity, left;
156 transition-duration: 2s, 4s;
157 }
159 </pre>This will cause the 'opacity' property to transition over a period of two seconds and the left property to transition over a period of four seconds.
160 </div>
162 <p id="list-matching">
163 In the case where the lists of values in transition properties
164 do not have the same length, the length of the
165 'transition-property' list determines the number of items in
166 each list examined when starting transitions. The lists are
167 matched up from the first value: excess values at the end are
168 not used. If one of the other properties doesn't have enough
169 comma-separated values to match the number of values of
170 'transition-property', the UA must calculate its used value by
171 repeating the list of values until there are enough. This
172 truncation or repetition does not affect the computed value.
173 <span class="note">
174 Note: This is analogous to the behavior of the 'background-*'
175 properties, with 'background-image' analogous to
176 'transition-property'.
177 </span>
178 </p>
180 <div class="example">
181 <p style="display:none">
182 Example(s):
183 </p>
184 <pre>
185 div {
186 transition-property: opacity, left, top, width;
187 transition-duration: 2s, 1s;
188 }
189 </pre>The above example defines a transition on the 'opacity' property of 2 seconds duration, a
190 transition on the 'left' property of 1
191 second duration, a transition on the 'top' property of 2 seconds duration and a
192 transition on the 'width' property of 1
193 second duration.
195 </div>
197 <p>
198 While authors can use transitions to create dynamically changing content,
199 dynamically changing content can lead to seizures in some users.
200 For information on how to avoid content that can lead to seizures, see
201 <a href="https://www.w3.org/TR/WCAG20/#seizure">Guideline 2.3:
202 Seizures:
203 Do not design content in a way that is known to cause seizures</a>
204 ([[WCAG20]]).
205 </p>
207 <!-- ======================================================================================================= -->
208 <h3 id="transition-property-property"><span id="the-transition-property-property-">
209 The 'transition-property' Property
210 </span></h3>
211 <p>
212 The 'transition-property' property specifies the name of the CSS property to which the transition is applied.
213 </p>
214 <pre class="propdef">
215 Name: transition-property
216 Value: ''transition-property/none'' | <<single-transition-property>>#
217 Initial: ''transition-property/all''
218 Applies to: all elements, ::before and ::after pseudo elements
219 Inherited: no
220 Animatable: no
221 Percentages: N/A
222 Media: visual
223 Computed value: Same as specified value.
224 Canonical order: <abbr title="follows order of property value definition">per grammar</abbr>
225 </pre>
227 <div class="prod">
228 <dfn type id="single-transition-property"><single-transition-property></dfn> = ''transition-property/all'' | <<custom-ident>>;
229 </div>
231 <p>
232 A value of
233 <dfn value for="transition-property">none</dfn>
234 means that no property will transition.
235 Otherwise, a list of properties to be transitioned, or the
236 keyword <dfn value for="transition-property">all</dfn>
237 which indicates that all properties are to be
238 transitioned, is given.
239 </p>
241 <p>
242 If one of the identifiers listed is not a recognized property
243 name or is not an animatable property, the implementation must
244 still start transitions on the animatable properties in the
245 list using the duration, delay, and timing function at their
246 respective indices in the lists for 'transition-duration',
247 'transition-delay', and 'transition-timing-function'. In other
248 words, unrecognized or non-animatable properties must be kept in
249 the list to preserve the matching of indices.
250 </p>
252 <p>
253 The <<custom-ident>> production in <<single-transition-property>>
254 also excludes the keyword ''transition-property/none'',
255 in addition to the keywords always excluded from <<custom-ident>>.
256 This means that
257 ''transition-property/none'', ''inherit'', and ''initial'' are not
258 permitted as items within a list of more that one identifier;
259 any list that uses them is syntactically invalid.
260 </p>
262 <p>
263 For the keyword ''transition-property/all'',
264 or if one of the identifiers listed is a
265 shorthand property, implementations must start transitions for
266 any of its longhand sub-properties that are animatable (or, for
267 ''transition-property/all'', all animatable properties), using the duration, delay,
268 and timing function at the index corresponding to the shorthand.
269 </p>
270 <p>
271 If a property is specified multiple times in the value of
272 'transition-property' (either on its own, via a shorthand that
273 contains it, or via the ''transition-property/all'' value), then the transition that
274 starts uses the duration, delay, and timing function at the
275 index corresponding to the <em>last</em> item in the value of
276 'transition-property' that calls for animating that property.
277 </p>
278 <p class="note">
279 Note: The ''transition-property/all'' value and 'all' shorthand
280 property work in similar ways, so the
281 ''transition-property/all'' value is just like a shorthand that
282 covers all properties.
283 </p>
285 <!-- ======================================================================================================= -->
286 <h3 id="transition-duration-property"><span id="the-transition-duration-property-">
287 The 'transition-duration' Property
288 </span></h3>
289 <p>
290 The 'transition-duration' property defines the length of time that a transition takes.
291 </p>
292 <pre class="propdef">
293 Name: transition-duration
294 Value: <<time>>#
295 Initial: ''0s''
296 Applies to: all elements, ::before and ::after pseudo elements
297 Inherited: no
298 Animatable: no
299 Percentages: N/A
300 Media: interactive
301 Computed value: Same as specified value.
302 Canonical order: <abbr title="follows order of property value definition">per grammar</abbr>
303 </pre>
304 <p>
305 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 'transition-duration' renders the declaration invalid.
306 </p>
308 <!-- =======================================================================================================
309 -->
311 <h3 id="transition-timing-function-property"><span id="transition-timing-function_tag">
312 The 'transition-timing-function' Property
313 </span></h3>
314 <p>
315 The 'transition-timing-function' property
316 describes how the intermediate values used during a transition will be
317 calculated. It allows for a transition to change speed over its
318 duration. These effects are commonly called <em>easing</em> functions.
319 In either case, a mathematical function that provides a smooth curve is
320 used.
321 </p>
322 <p>
323 Timing functions are either defined as a stepping function or
324 a <a
325 href="http://en.wikipedia.org/wiki/B%C3%A9zier_curve#Cubic_B.C3.A9zier_curves">cubic
326 Bézier curve</a>.
327 The timing function takes as its input
328 the current elapsed percentage of the transition duration
329 and outputs the percentage of the way the transition is
330 from its start value to its end value.
331 How this output is used is defined by
332 the <a href="#animatable-types">interpolation rules</a>
333 for the value type.
334 </p>
335 <p>
336 A <a href="http://en.wikipedia.org/wiki/Step_function">stepping</a>
337 function is defined by a number that divides the domain of operation
338 into equally sized intervals. Each subsequent interval is a equal step
339 closer to the goal state. The function also specifies whether the
340 change in output percentage happens at the start or end of the
341 interval (in other words, if 0% on the input percentage is the point
342 of initial change).
343 </p>
344 <div class="figure">
345 <img src="step.png" alt="The step timing function splits
346 the function domain into a number of disjoint straight line
347 segments. steps(1, start) is a function whose
348 output value is 1 for all input values. steps(1, end) is a function whose
349 output value is 0 for all input values less than 1, and output
350 is 1 for the input value of 1. steps(3, start) is a function that
351 divides the input domain into three segments, each 1/3 in length,
352 and 1/3 above the previous segment, with the first segment starting
353 at 1/3. steps(3, end) is a function that
354 divides the input domain into three segments, each 1/3 in length,
355 and 1/3 above the previous segment, with the first segment starting
356 at 0.">
357 </div>
358 <p class="caption">
359 Step timing functions
360 </p>
361 <p>
362 A <a
363 href="http://en.wikipedia.org/wiki/B%C3%A9zier_curve#Cubic_B.C3.A9zier_curves">cubic
364 Bézier curve</a> is defined by four control points, P<sub>0</sub>
365 through P<sub>3</sub> (see Figure 1). P<sub>0</sub> and P<sub>3</sub>
366 are always set to (0,0) and (1,1). The 'transition-timing-function' property is used
367 to specify the values for points P<sub>1</sub> and P<sub>2</sub>. These
368 can be set to preset values using the keywords listed below, or can be
369 set to specific values using the ''cubic-bezier()'' function.
370 In the ''cubic-bezier()'' function, P<sub>1</sub> and
371 P<sub>2</sub> are each specified by both an X and Y value.
372 </p>
373 <div class="figure">
374 <img src="TimingFunction.png" alt="The Bézier timing function is a
375 smooth curve from point P0 = (0,0) to point P3 = (1,1). The
376 length and orientation of the line segment P0-P1 determines
377 the tangent and the curvature of the curve at P0 and the
378 line segment P2-P3 does the same at P3.">
379 </div>
380 <p class="caption">
381 Bézier Timing Function Control Points
382 </p>
383 <pre class="propdef">
384 Name: transition-timing-function
385 Value: <<single-transition-timing-function>>#
386 Initial: ''transition-timing-function/ease''
387 Applies to: all elements, ::before and ::after pseudo elements
388 Inherited: no
389 Animatable: no
390 Percentages: N/A
391 Media: interactive
392 Computed value: Same as specified value.
393 Canonical order: <abbr title="follows order of property value definition">per grammar</abbr>
394 </pre>
395 <div class="prod">
396 <dfn type id="single-transition-timing-function"><single-transition-timing-function></dfn> = ''ease'' | ''linear'' | ''ease-in'' | ''ease-out'' | ''ease-in-out'' | ''step-start'' | ''step-end'' | <a lt="steps()" function>steps</a>(<<integer>>[, [ ''start'' | ''end'' ] ]?) | <a lt="cubic-bezier()" function>cubic-bezier</a>(<<number>>, <<number>>, <<number>>, <<number>>)
397 </div>
398 <p>
399 The timing functions have the following definitions.
400 </p>
401 <dl dfn-type="value" dfn-for="transition-timing-function, <single-transition-timing-function>">
402 <dt><dfn>ease</dfn></dt>
403 <dd>
404 The ease function is equivalent to <a lt="cubic-bezier()" function>cubic-bezier(0.25, 0.1, 0.25, 1)</a>.
405 </dd>
406 <dt><dfn>linear</dfn></dt>
407 <dd>
408 The linear function is equivalent to <a lt="cubic-bezier()" function>cubic-bezier(0, 0, 1, 1)</a>.
409 </dd>
410 <dt><dfn>ease-in</dfn></dt>
411 <dd>
412 The ease-in function is equivalent to <a lt="cubic-bezier()" function>cubic-bezier(0.42, 0, 1, 1)</a>.
413 </dd>
414 <dt><dfn>ease-out</dfn></dt>
415 <dd>
416 The ease-out function is equivalent to <a lt="cubic-bezier()" function>cubic-bezier(0, 0, 0.58, 1)</a>.
417 </dd>
418 <dt><dfn>ease-in-out</dfn></dt>
419 <dd>
420 The ease-in-out function is equivalent to <a lt="cubic-bezier()" function>cubic-bezier(0.42, 0, 0.58, 1)</a>.
421 </dd>
422 <dt><dfn>step-start</dfn></dt>
423 <dd>
424 The step-start function is equivalent to <a lt="steps()" function>steps(1, start)</a>.
425 </dd>
426 <dt><dfn>step-end</dfn></dt>
427 <dd>
428 The step-end function is equivalent to <a lt="steps()" function>steps(1, end)</a>.
429 </dd>
430 <dt><dfn function lt="steps()">steps(<<integer>>[, [ start | end ] ]?)</dfn></dt>
431 <dd>
432 Specifies a stepping function, described above, taking two
433 parameters. The first parameter specifies the number of intervals
434 in the function. It must be a positive integer (greater than 0).
435 The second parameter, which is optional, is
436 either the value <dfn value for="steps()">start</dfn> or <dfn value for="steps()">end</dfn>, and specifies the point
437 at which the change of values occur within the interval.
438 If the second parameter is omitted, it is given the value ''end''.
439 </dd>
440 <dt><dfn function lt="cubic-bezier()">cubic-bezier(<<number>>, <<number>>, <<number>>, <<number>>)</dfn></dt>
441 <dd>
442 Specifies a <a
443 href="http://en.wikipedia.org/wiki/B%C3%A9zier_curve">cubic-bezier
444 curve</a>. The four values specify points P<sub>1</sub> and
445 P<sub>2</sub> of the curve as (<var>x1</var>, <var>y1</var>, <var>x2</var>, <var>y2</var>). Both x values must be
446 in the range [0, 1] or the definition is invalid. The y values can
447 exceed this range.
448 </dd>
449 </dl><!-- ======================================================================================================= -->
450 <h3 id="transition-delay-property"><span id="the-transition-delay-property-">
451 The 'transition-delay' Property
452 </span></h3>
453 <p>
454 The 'transition-delay' 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 'transition-delay' 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.
455 </p>
456 <p>
457 If the value for 'transition-delay' 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 'transition-delay', the starting values are taken from the moment the property is changed.
458 </p>
459 <pre class="propdef">
460 Name: transition-delay
461 Value: <<time>>#
462 Initial: ''0s''
463 Applies to: all elements, ::before and ::after pseudo elements
464 Inherited: no
465 Animatable: no
466 Percentages: N/A
467 Media: interactive
468 Computed value: Same as specified value.
469 Canonical order: <abbr title="follows order of property value definition">per grammar</abbr>
470 </pre><!-- ======================================================================================================= -->
471 <h3 id="transition-shorthand-property"><span id="the-transition-shorthand-property-">
472 The 'transition' Shorthand Property
473 </span></h3>
474 <p>
475 The 'transition' shorthand property combines the four properties described above into a single property.
476 </p>
477 <pre class="propdef">
478 Name: transition
479 Value: <<single-transition>>#
480 Initial: see individual properties
481 Applies to: all elements, ::before and ::after pseudo elements
482 Inherited: no
483 Animatable: no
484 Percentages: N/A
485 Media: interactive
486 Computed value: see individual properties
487 Canonical order: <abbr title="follows order of property value definition">per grammar</abbr>
488 </pre>
490 <div class="prod">
491 <dfn type id="single-transition"><single-transition></dfn> = [ ''none'' | <<single-transition-property>> ] || <<time>> || <<single-transition-timing-function>> || <<time>>
492 </div>
494 <p>
495 Note that order is important within the items in this property:
496 the first value that can be parsed as a time is assigned to the
497 transition-duration,
498 and the second value that can be parsed as a time is assigned to
499 transition-delay.
500 </p>
502 <p>
503 If there is more than one <<single-transition>> in the shorthand,
504 and any of the transitions has
505 ''none'' as the <<single-transition-property>>,
506 then the declaration is invalid.
507 </p>
509 <h2 id="starting">
510 Starting of transitions
511 </h2>
513 <p>
514 Implementations must maintain a set of
515 <dfn export lt="running transition">running transitions</dfn>,
516 each of which applies to a specific element and non-shorthand
517 property. Each of these transitions also has a
518 <dfn export for="transition">start time</dfn>, <dfn export for="transition">end time</dfn>,
519 <dfn export for="transition">start value</dfn>, <dfn export for="transition">end value</dfn>,
520 <dfn export for="transition">reversing-adjusted start value</dfn>, and <dfn export for="transition">reversing shortening factor</dfn>.
521 Transitions are added to this set as described in this section,
522 and are removed from this set
523 when they <a>complete</a>
524 or when implementations are required to <dfn export for="transition">cancel</dfn> them.
525 <span class="note">
526 For the rationale behind the <a>reversing-adjusted start value</a>
527 and <a>reversing shortening factor</a>, see [[#reversing]].
528 </span>
529 </p>
531 <p>
532 Implementations must also maintain a set of
533 <dfn export lt="completed transition">completed transitions</dfn>,
534 each of which
535 (like <a>running transitions</a>)
536 applies to a specific element and non-shorthand property.
537 <span class="note">
538 This specification maintains the invariant that
539 there is never both a <a>running transition</a> and
540 a <a>completed transition</a> for the same property and element.
541 </span>
542 </p>
544 <p>
545 If an element is no longer in the document,
546 implementations must remove transitions on it
547 from the <a>running transitions</a> and the
548 <a>completed transitions</a>.
549 </p>
551 <div class="note">
553 <p>
554 This set of completed transitions
555 needs to be maintained
556 in order to prevent
557 transitions from repeating themselves in certain cases,
558 i.e., to maintain the invariant
559 that this specification tries to maintain
560 that unrelated style changes do not trigger transitions.
561 </p>
563 <p class="example">
564 An example where maintaining the set of completed transitions
565 is necessary would be a transition on
566 an inherited property,
567 where the parent specifies a transition of that property for
568 a longer duration (say, ''transition: 4s text-indent'')
569 and a child element that inherits the parent's value specifies
570 a transition of the same property for a shorter duration
571 (say, ''transition: 1s text-indent'').
572 Without the maintenance of this set of completed transitions,
573 implementations could start additional transitions on the child
574 after the initial 1 second transition on the child completes.
575 </p>
577 </div>
579 <p>
580 Various things can cause the <a>computed values</a> of properties
581 on an element to change.
582 These include
583 insertion and removal of elements from the document tree
584 (which both changes whether those elements have <a>computed values</a> and
585 can change the styles of other elements through selector matching),
586 changes to the document tree that cause
587 changes to which selectors match elements,
588 changes to style sheets or style attributes,
589 and other things.
590 This specification does not define when <a>computed values</a> are updated,
591 beyond saying that implementations must not
592 use, present, or display something resulting from the CSS
593 cascading, value computation, and inheritance process [[!CSS3CASCADE]]
594 without updating the <a>computed value</a>
595 (which means merely that implementations cannot avoid
596 meeting requirements of this specification
597 by claiming not to have updated the <a>computed value</a>
598 as part of handling a style change).
599 However,
600 when an implementation updates the <a>computed value</a> of a
601 property on an element
602 to reflect one of these changes,
603 or computes the <a>computed value</a> of a property on an element
604 newly added to the document,
605 it must update the <a>computed value</a>
606 for all properties and elements to reflect all
607 of these changes at the same time
608 (or at least it must be undetectable that it was done at a
609 different time).
610 This processing of a set of simultaneous style changes is called a
611 <dfn export>style change event</dfn>.
612 (Implementations typically have a <a>style change event</a> to
613 correspond with their desired screen refresh rate,
614 and when up-to-date computed style or layout information is needed
615 for a script API that depends on it.)
616 </p>
618 <p>
619 Since this specification does not define
620 when a <a>style change event</a> occurs,
621 and thus what changes to computed values are considered simultaneous,
622 authors should be aware that changing any of the transition
623 properties a small amount of time after making a change that
624 might transition can result in behavior that varies between
625 implementations, since the changes might be considered
626 simultaneous in some implementations but not others.
627 </p>
629 <p>
630 When a <a>style change event</a> occurs,
631 implementations must start transitions based on
632 the <a>computed values</a> that changed in that event.
633 If an element is not in the document during that
634 style change even or was not in the document during
635 the previous style change event,
636 then transitions are not started for that element
637 in that style change event.
638 Otherwise,
639 define the <dfn export>before-change style</dfn> as
640 the <a>computed values</a> of all properties on the element as of
641 the previous <a>style change event</a>,
642 except with any styles derived from declarative
643 animations such as CSS Transitions, CSS Animations
644 ([[CSS3-ANIMATIONS]]),
645 and SMIL Animations ([[SMIL-ANIMATION]], [[SVG11]])
646 updated to the current time.
647 Likewise, define the <dfn export>after-change style</dfn> as
648 the <a>computed values</a> of all properties
649 on the element based on the information
650 known at the start of that <a>style change event</a>,
651 but excluding any styles from CSS Transitions in the computation,
652 and inheriting from
653 the <a>after-change style</a> of the parent.
654 </p>
656 <div class="note">
657 <p>
658 Note that this definition of the <a>after-change style</a>
659 means that a single change
660 can start a transition on the same property
661 on both an ancestor element and its descendant element.
662 This can happen when a property change is inherited
663 from one element with 'transition-*' properties
664 that say to animate the changing property
665 to another element with 'transition-*' properties
666 that also say to animate the changing property.
667 </p>
669 <p>
670 When this happens, both transitions will run,
671 and the transition on the descendant will override
672 the transition on the ancestor
673 because of the normal
674 CSS cascading and inheritance rules ([[CSS3CASCADE]]).
675 </p>
677 <p>
678 If the transition on the descendant completes before
679 the transition on the ancestor,
680 the descendant will then resume inheriting
681 the (still transitioning) value from its parent.
682 This effect is likely not a desirable effect,
683 but it is essentially doing what the author asked for.
684 </p>
685 </div>
687 <p>
688 For each element with a <a>before-change style</a> and
689 an <a>after-change style</a>,
690 and each property (other than shorthands),
691 define the <dfn export>matching transition-property value</dfn> as
692 the last value in the
693 'transition-property' in the element's <a>after-change style</a>
694 that matches the property,
695 as described in
696 [[#transition-property-property]].
697 If there is such a value, then corresponding to it, there is
698 a <dfn export>matching transition duration</dfn>,
699 a <dfn export>matching transition delay</dfn>, and
700 a <dfn export>matching transition timing function</dfn>
701 in the values in the <a>after-change style</a> of
702 'transition-duration', 'transition-delay', and 'transition-timing-function'
703 (see <a href="#list-matching">the rules on matching lists</a>).
704 Define the <dfn export for="transition">combined duration</dfn> of the transition
705 as the sum of max(<a>matching transition duration</a>, ''0s'') and
706 the <a>matching transition delay</a>.
707 For each element and property, the implementation must act
708 as follows:
709 </p>
711 <ol>
712 <li>
713 If all of the following are true:
714 <ul>
715 <li>
716 the element does not have
717 a <a>running transition</a> for the property,
718 </li>
719 <li>
720 the <a>before-change style</a> is different from
721 and can be interpolated with
722 the <a>after-change style</a> for that property,
723 </li>
724 <li>
725 the element does not have a <a>completed transition</a>
726 for the property
727 or the <a>end value</a> of the <a>completed transition</a>
728 is different from the <a>after-change style</a> for the property,
729 </li>
730 <li>
731 there is a <a>matching transition-property value</a>, and
732 </li>
733 <li>
734 the <a>combined duration</a> is greater than ''0s'',
735 </li>
736 </ul>
737 then implementations must
738 remove the <a>completed transition</a> (if present) from the set
739 of completed transitions and
740 start a transition whose:
741 <ul>
742 <li>
743 <a>start time</a> is
744 the time of the <a>style change event</a> plus
745 the <a>matching transition delay</a>,
746 </li>
747 <li>
748 <a>end time</a> is
749 the <a>start time</a> plus
750 the <a>matching transition duration</a>,
751 </li>
752 <li>
753 <a>start value</a> is
754 the value of the transitioning property
755 in the <a>before-change style</a>,
756 </li>
757 <li>
758 <a>end value</a> is
759 the value of the transitioning property
760 in the <a>after-change style</a>,
761 </li>
762 <li>
763 <a>reversing-adjusted start value</a> is the same as
764 the <a>start value</a>, and
765 <li>
766 <a>reversing shortening factor</a> is 1.
767 </li>
768 </ul>
769 </li>
770 <li>
771 Otherwise,
772 if the element has a <a>completed transition</a> for the property
773 and the <a>end value</a> of the <a>completed transition</a>
774 is different from the <a>after-change style</a> for the property,
775 then implementations must
776 remove the <a>completed transition</a> from the set of
777 <a>completed transitions</a>.
778 </li>
779 <li>
780 If the element has a <a>running transition</a> or
781 <a>completed transition</a> for the property,
782 and there is <strong>not</strong>
783 a <a>matching transition-property value</a>,
784 then implementations must
785 <a>cancel</a> the <a>running transition</a>
786 or remove the <a>completed transition</a> from the set of
787 <a>completed transitions</a>.
788 </li>
789 <li>
790 If the element has a <a>running transition</a> for the property,
791 there is a <a>matching transition-property value</a>,
792 and the <a>end value</a> of the <a>running transition</a> is
793 <strong>not</strong> equal to the value of the property in the
794 <a>after-change style</a>, then:
795 <ol>
796 <li>
797 If the <a>current value</a> of the property
798 in the <a>running transition</a>
799 is equal to
800 the value of the property in the <a>after-change style</a>,
801 or if these two values cannot be interpolated,
802 then implementations must
803 <a>cancel</a> the <a>running transition</a>.
804 </li>
805 <li>
806 Otherwise, if the <a>combined duration</a> is
807 less than or equal to ''0s'',
808 or if the
809 <a>current value</a> of the property in the <a>running transition</a>
810 cannot be interpolated with
811 the value of the property in the <a>after-change style</a>,
812 then implementations must
813 <a>cancel</a> the <a>running transition</a>.
814 </li>
815 <li>
816 Otherwise, if the <a>reversing-adjusted start value</a>
817 of the <a>running transition</a> is the same as the value of
818 the property in the <a>after-change style</a>
819 <span class="note">(see the
820 <a href="#reversing">section on reversing of
821 transitions</a> for why these case exists)</span>,
822 implementations must
823 <a>cancel</a> the <a>running transition</a> and
824 start a new transition whose:
825 <ul>
826 <li>
827 <a>reversing-adjusted start value</a> is
828 the <a>end value</a> of the
829 <a>running transition</a>
830 <span class="note">(Note: This represents the logical start state of
831 the transition, and allows some calculations to ignore that
832 the transition started before that state was reached, which
833 in turn allows repeated reversals of the same transition to
834 work correctly),</span>
835 <li>
836 <a>reversing shortening factor</a>
837 is the absolute value, clamped to the range [0, 1],
838 of the sum of:
839 <ol>
840 <li>the output of the timing function of the old transition
841 at the time of the <a>style change event</a>,
842 times the <a>reversing shortening factor</a> of the
843 old transition</li>
844 <li>1 minus the <a>reversing shortening factor</a> of
845 the old transition.</li>
846 </ol>
847 <span class="note">Note: This represents the portion of the
848 space between the <a>reversing-adjusted start value</a>
849 and the <a>end value</a> that the old transition has
850 traversed (in amounts of the value, not time), except with the
851 absolute value and clamping to handle timing functions that
852 have y1 or y2 outside the range [0, 1].</span>
853 </li>
854 <li>
855 <a>start time</a> is
856 the time of the <a>style change event</a> plus:
857 <ol>
858 <li>if the <a>matching transition delay</a>
859 is nonnegative,
860 the <a>matching transition delay</a>, or
861 <li>if the <a>matching transition delay</a>
862 is negative,
863 the product of
864 the new transition's
865 <a>reversing shortening factor</a> and
866 the <a>matching transition delay</a>,
867 </ol>
868 </li>
869 <li>
870 <a>end time</a> is
871 the <a>start time</a> plus the product of
872 the <a>matching transition duration</a> and
873 the new transition's <a>reversing shortening factor</a>,
874 </li>
875 <li>
876 <a>start value</a> is
877 the <a>current value</a> of the property
878 in the <a>running transition</a>,
879 </li>
880 <li>
881 <a>end value</a> is
882 the value of the property
883 in the <a>after-change style</a>,
884 </li>
885 </ul>
886 </li>
887 <li>
888 Otherwise, implementations must
889 <a>cancel</a> the <a>running transition</a>
890 and start a new transition whose:
891 <ul>
892 <li>
893 <a>start time</a> is
894 the time of the <a>style change event</a> plus
895 the <a>matching transition delay</a>,
896 </li>
897 <li>
898 <a>end time</a> is
899 the <a>start time</a> plus
900 the <a>matching transition duration</a>,
901 </li>
902 <li>
903 <a>start value</a> is
904 the <a>current value</a> of the property
905 in the <a>running transition</a>,
906 </li>
907 <li>
908 <a>end value</a> is
909 the value of the property
910 in the <a>after-change style</a>,
911 </li>
912 <li>
913 <a>reversing-adjusted start value</a> is the same as
914 the <a>start value</a>, and
915 <li>
916 <a>reversing shortening factor</a> is 1.
917 </li>
918 </ul>
919 </li>
920 </ol>
921 </li>
923 </ol>
925 <div class="note">
926 <p>
927 Note that the above rules mean that
928 when the computed value of an animatable property changes,
929 the transitions that start are based on the
930 values of the 'transition-property', 'transition-duration',
931 'transition-timing-function', and 'transition-delay' properties
932 at the time the animatable property would first have its new
933 computed value.
934 This means that when one of these 'transition-*' properties
935 changes at the same time as
936 a property whose change might transition,
937 it is the <em>new</em> values of the 'transition-*' properties
938 that control the transition.
939 </p>
940 <div class="example" id="manual-reversing-example">
941 <p style="display:none">
942 Example(s):
943 </p>
944 <p>This provides a way for authors to specify different values
945 of the 'transition-*' properties for the “forward”
946 and “reverse” transitions,
947 when the transitions are between two states
948 (but see <a
949 href="#reversing">below</a> for special reversing behavior when
950 an <em>incomplete</em> transition is interrupted). Authors can
951 specify the value of 'transition-duration',
952 'transition-timing-function', or 'transition-delay' in the same
953 rule where they specify the value that triggers the transition,
954 or can change these properties at the same time as they change
955 the property that triggers the transition. Since it's the new
956 values of these 'transition-*' properties that affect the
957 transition, these values will be used for the transitions
958 <em>to</em> the associated transitioning values. For example:
959 </p>
960 <pre>
961 li {
962 transition: background-color linear 1s;
963 background: blue;
964 }
965 li:hover {
966 background-color: green;
967 transition-duration: 2s; /* applies to the transition *to* the :hover state */
968 }</pre>
969 <p>
970 When a list item with these style rules enters the :hover
971 state, the computed 'transition-duration' at the time that
972 'background-color' would have its new value (''green'') is ''2s'',
973 so the transition from ''blue'' to ''green'' takes 2 seconds.
974 However, when the list item leaves the :hover state, the
975 transition from ''green'' to ''blue'' takes 1 second.
976 </p>
977 </div>
978 </div>
980 <p class="note">
981 Note that once the transition of a property has started
982 (including being in its delay phase),
983 it continues running based on
984 the original timing function, duration, and
985 delay, even if the 'transition-timing-function',
986 'transition-duration', or 'transition-delay' property changes
987 before the transition is complete. However, if the
988 'transition-property' property changes such that the transition
989 would not have started, the transition stops (and the
990 property immediately changes to its final value).
991 </p>
993 <p class="note">
994 Note that above rules mean that
995 transitions do not start when the computed
996 value of a property changes as a result of declarative animation
997 (as opposed to scripted animation).
998 This happens because the before-change style includes up-to-date
999 style for declarative animations.
1000 </p>
1002 <h3 id="reversing">
1003 Faster reversing of interrupted transitions
1004 </h3>
1005 <div class="note">
1007 <p>
1008 Many common transitions effects involve transitions between two states,
1009 such as the transition that occurs when the mouse pointer moves
1010 over a user interface element, and then later moves out of that element.
1011 With these effects, it is common for a running transition
1012 to be interrupted before it completes,
1013 and the property reset to the starting value of that transition.
1014 An example is a hover effect on an element,
1015 where a transition starts when the pointer enters the element,
1016 and then the pointer exits the element before the effect has completed.
1017 If the outgoing and incoming transitions
1018 are executed using their specified durations and timing functions,
1019 the resulting effect can be distractingly asymmetric
1020 because the second transition
1021 takes the full specified time to move a shortened distance.
1022 Instead, this specification makes second transition shorter.
1023 </p>
1025 <p>
1026 The mechanism the above rules use to cause this involves the
1027 <a>reversing shortening factor</a> and the
1028 <a>reversing-adjusted start value</a>.
1029 In particular, the reversing behavior is present whenever
1030 the <a>reversing shortening factor</a> is less than 1.
1031 </p>
1033 <p class="note">
1034 Note that these rules do not fully address the problem for
1035 transition patterns that involve more than two states.
1036 </p>
1038 <p class="note">
1039 Note that these rules lead to the entire timing function of the
1040 new transition being used, rather than jumping into the middle
1041 of a timing function, which can create a jarring effect.
1042 </p>
1044 <p class="note">
1045 This was one of several possibilities that was considered by the
1046 working group. See the
1047 <a href="transition-reversing-demo">reversing demo</a>
1048 demonstrating a number of them, leading to a working group
1049 resolution made on 2013-06-07 and edits made on 2013-11-11.
1050 </p>
1052 </div>
1054 <h2 id="application">
1055 Application of transitions
1056 </h2>
1058 <p>
1059 When a property on an element is undergoing a transition
1060 (that is, when or after the transition has started and before the
1061 <a>end time</a> of the transition)
1062 the transition adds a style called the <dfn export>current value</dfn>
1063 to the CSS cascade
1064 at the level defined for CSS Transitions in [[!CSS3CASCADE]].
1065 </p>
1067 <p class="note">
1068 Note that this means that computed values
1069 resulting from CSS transitions
1070 can inherit to descendants just like
1071 any other computed values.
1072 In the normal case, this means that
1073 a transition of an inherited property
1074 applies to descendant elements
1075 just as an author would expect.
1076 </p>
1078 <p>
1079 Implementations must add this value to the cascade
1080 if and only if
1081 that property is not currently
1082 undergoing a CSS Animation ([[!CSS3-ANIMATIONS]]) on the same element.
1083 </p>
1085 <p class="note">
1086 Note that this behavior of transitions not applying to the cascade
1087 when an animation on the same element and property is running
1088 does not affect whether the transition has started or ended.
1089 APIs that detect whether transitions are running
1090 (such as <a href="#transition-events">transition events</a>)
1091 still report that a transition is running.
1092 </p>
1094 <p>
1095 If the current time is at or before the
1096 <a>start time</a> of the transition
1097 (that is, during the delay phase of the transition),
1098 the <a>current value</a> is a specified style that will compute
1099 to the <a>start value</a> of the transition.
1100 </p>
1102 <p>
1103 If the current time is after the
1104 <a>start time</a> of the transition
1105 (that is, during the duration phase of the transition),
1106 the <a>current value</a> is a specified style that will compute
1107 to the <a href="#animatable-types">result of interpolating the property</a>
1108 using the <a>start value</a> of the transition as
1109 <var>V</var><sub>start</sub>,
1110 using the <a>end value</a> of the transition as
1111 <var>V</var><sub>end</sub>,
1112 and using (current time - start time) / (end time - start time)
1113 as the input to the timing function.
1114 </p>
1116 <h2 id="complete">Completion of transitions</h2>
1118 <p>
1119 <a>Running transitions</a>
1120 <dfn export for="transition" id="dfn-complete">complete</dfn>
1121 at a time that equal to or after their end time,
1122 but prior to to the first <a>style change event</a>
1123 whose time is equal to or after their <a>end time</a>.
1124 When a transition completes,
1125 implementations must move
1126 all transitions that complete at that time
1127 from the set of <a>running transitions</a>
1128 to the set of <a>completed transitions</a>
1129 and then fire the <a href="#transition-events">events</a>
1130 for those completions.
1131 <span class="note">(Note that doing otherwise, that is,
1132 firing some of the events before doing all of the moving
1133 from <a>running transitions</a> to <a>completed transitions</a>,
1134 could allow
1135 a style change event to happen
1136 without the necessary transitions completing,
1137 since firing the event could cause a style change event,
1138 if an event handler requests up-to-date computed style or
1139 layout data.)</span>
1140 </p>
1142 <h2 id="transition-events"><span id="transition-events-">
1143 Transition Events
1144 </span></h2>
1145 <p>
1146 The completion of a CSS Transition generates a corresponding <a href="https://www.w3.org/TR/DOM-Level-2-Events/events.html">DOM Event</a>.
1147 An event is <a>dispatched</a> to the element
1148 for each property that undergoes a transition on that element.
1149 This allows a content developer to perform actions that synchronize
1150 with the completion of a transition.
1151 </p>
1152 <p>
1153 Each event provides the name of the property the transition is
1154 associated with as well as the duration of the transition.
1155 </p>
1156 <dl>
1157 <dt>
1158 <b>Interface <dfn interface id="Events-TransitionEvent">TransitionEvent</dfn></b>
1159 </dt>
1160 <dd>
1161 <p>
1162 The {{TransitionEvent}} interface provides specific contextual information associated with transitions.
1163 </p>
1164 <dl>
1165 <dt>
1166 <b>IDL Definition</b>
1167 </dt>
1168 <dd>
1169 <div class='idl-code'>
1170 <pre class='idl'>
1171 [Constructor(DOMString type, optional TransitionEventInit transitionEventInitDict)]
1172 interface TransitionEvent : Event {
1173 readonly attribute DOMString propertyName;
1174 readonly attribute float elapsedTime;
1175 readonly attribute DOMString pseudoElement;
1176 };
1178 dictionary TransitionEventInit : EventInit {
1179 DOMString propertyName = "";
1180 float elapsedTime = 0.0;
1181 DOMString pseudoElement = "";
1182 };
1183 </pre>
1184 </div>
1185 </dd>
1186 <dt>
1187 <b>Attributes</b>
1188 </dt>
1189 <dd>
1190 <dl>
1191 <dt>
1192 <code class='attribute-name'><dfn attribute for="TransitionEvent" id="Events-TransitionEvent-propertyName">propertyName</dfn></code> of type <code>DOMString</code>, readonly
1193 </dt>
1194 <dd>
1195 The name of the CSS property associated with the transition.
1196 </dd>
1197 </dl>
1198 <dl>
1199 <dt>
1200 <code class='attribute-name'><dfn attribute for="TransitionEvent" id="Events-TransitionEvent-elapsedTime">elapsedTime</dfn></code> of type <code>float</code>, readonly
1201 </dt>
1202 <dd>
1203 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>.
1204 </dd>
1205 </dl>
1206 <dl>
1207 <dt>
1208 <code class='attribute-name'><dfn attribute for="TransitionEvent" id="Events-TransitionEvent-pseudoElement">pseudoElement</dfn></code> of type <code>DOMString</code>, readonly
1209 </dt>
1210 <dd>
1211 The name (beginning with two colons) of the CSS
1212 pseudo-element on which the transition occurred (in
1213 which case the target of the event is that
1214 pseudo-element's corresponding element), or the empty
1215 string if the transition occurred on an element (which
1216 means the target of the event is that element).
1217 </dd>
1218 </dl>
1219 </dd>
1220 </dl>
1221 <p>
1222 <code id="TransitionEvent-constructor">TransitionEvent(type, transitionEventInitDict)</code>
1223 is an <a>event constructor</a>.
1224 </p>
1225 </dd>
1226 </dl>
1227 <p>
1228 There is one type of transition event available.
1229 </p>
1230 <dl>
1231 <dt>
1232 <b><dfn event for="Element" id="transitionend">transitionend</dfn></b>
1233 </dt>
1234 <dd>
1235 The {{transitionend}} event occurs at the completion of the transition. In the
1236 case where a transition is removed before completion, such as if the
1237 transition-property is removed, then the event will not fire.
1238 <ul>
1239 <li>Bubbles: Yes
1240 </li>
1241 <li>Cancelable: No
1242 </li>
1243 <li>Context Info: propertyName, elapsedTime, pseudoElement
1244 </li>
1245 </ul>
1246 </dd>
1247 </dl>
1249 <h2 id="animatable-types"><span id="animation-of-property-types-">
1250 Animation of property types
1251 </span></h2>
1253 <p>
1254 Some property types can be interpolated,
1255 which means they can animate smoothly from one value to another.
1256 Other property types cannot, and thus animate only in a single
1257 step from one value to the other.
1258 </p>
1260 <h3 id="interpolated-types">Animation of interpolated property types</h3>
1262 <p>
1263 When interpolating between two values,
1264 <var>V</var><sub>start</sub> and <var>V</var><sub>end</sub>,
1265 interpolation is done using the output <var>p</var> of the timing function,
1266 which gives the portion of the value space
1267 that the interpolation has crossed.
1268 Thus the result of the interpolation is
1269 <var>V</var><sub>res</sub> =
1270 (1 - <var>p</var>) ⋅ <var>V</var><sub>start</sub> +
1271 <var>p</var> ⋅ <var>V</var><sub>end</sub>.
1272 </p>
1274 <p>
1275 However, if this value (<var>V</var><sub>res</sub>)
1276 is outside the allowed range of values for the property,
1277 then it is clamped to that range.
1278 This can occur if <var>p</var> is outside of the range 0 to 1,
1279 which can occur if a timing function is specified
1280 with a <var>y1</var> or <var>y2</var> that is outside the range 0 to 1.
1281 </p>
1283 <p>
1284 The following describes how each property type undergoes transition or
1285 animation.
1286 </p>
1288 <ul>
1289 <li id="animtype-color">
1290 <strong>color</strong>: interpolated via red, green, blue and alpha
1291 components (treating each as a number, see below).
1292 The interpolation is done between premultiplied colors
1293 (that is, colors for which the red, green, and blue components
1294 specified have been multiplied by the alpha).
1295 </li>
1296 <li id="animtype-length">
1297 <strong>length</strong>: interpolated as real numbers.
1298 </li>
1299 <li id="animtype-percentage">
1300 <strong>percentage</strong>: interpolated as real numbers.
1301 </li>
1302 <li id="animtype-lpcalc">
1303 <strong>length, percentage, or calc</strong>: when both values
1304 are lengths, interpolated as lengths; when both values are
1305 percentages, interpolated as percentages; otherwise, both
1306 values are converted into a ''calc()'' function that is the
1307 sum of a length and a percentage (each possibly zero), and
1308 these ''calc()'' functions have each half interpolated as real
1309 numbers.
1310 </li>
1311 <li id="animtype-integer">
1312 <strong>integer</strong>: interpolated via discrete steps (whole
1313 numbers). The interpolation happens in real number space and is
1314 converted to an integer by rounding to the nearest integer, with
1315 values halfway between a pair of integers rounded towards
1316 positive infinity.
1317 </li>
1318 <li id="animtype-font-weight">
1319 <strong>font weight</strong>: interpolated via discrete steps
1320 (multiples of 100). The interpolation happens in real number
1321 space and is converted to an integer by rounding to the
1322 nearest multiple of 100, with values halfway between multiples
1323 of 100 rounded towards positive infinity.
1324 </li>
1325 <li id="animtype-number">
1326 <strong>number</strong>: interpolated as real (floating point)
1327 numbers.
1328 </li>
1329 <li id="animtype-rect">
1330 <strong>rectangle</strong>: interpolated via the x, y,
1331 width and height components (treating each as a number).
1332 </li>
1333 <li id="animtype-visibility">
1334 <strong>visibility</strong>: if one of the values is
1335 ''visibility/visible'', interpolated as a discrete step where values of the
1336 timing function between 0 and 1 map to ''visibility/visible'' and other
1337 values of the timing function (which occur only at the
1338 start/end of the transition or as a result of ''cubic-bezier()''
1339 functions with Y values outside of [0, 1]) map to the closer
1340 endpoint; if neither value is ''visibility/visible'' then not interpolable.
1341 </li>
1342 <li id="animtype-shadow-list">
1343 <strong>shadow list</strong>: Each shadow in the list
1344 (treating ''shadow/none'' as a 0-length list)
1345 is interpolated via the
1346 color (as <a href="#animtype-color">color</a>) component,
1347 and x, y, blur, and (when appropriate) spread
1348 (as <a href="#animtype-length">length</a>) components.
1349 For each shadow, if both input shadows are ''shadow/inset''
1350 or both input shadows are not ''shadow/inset'',
1351 then the interpolated shadow must match the input shadows in that regard.
1352 If any pair of input shadows has one ''shadow/inset'' and the other not ''shadow/inset'',
1353 the entire <a href="#animtype-shadow-list">shadow-list</a> is uninterpolable.
1354 If the lists of shadows have different lengths,
1355 then the shorter list is padded at the end
1356 with shadows whose color is ''transparent'',
1357 all lengths are ''0'',
1358 and whose ''shadow/inset'' (or not) matches the longer list.
1359 </li>
1360 <li id="animtype-gradient">
1361 <strong>gradient</strong>: interpolated via the
1362 positions and colors of each stop. They must have the same type
1363 (radial or linear) and same number of stops in order to be animated.
1364 <span class="note">Note: [[CSS3-IMAGES]] may extend this
1365 definition.</span>
1366 </li>
1367 <li id="animtype-paintserver">
1368 <strong>paint server</strong> (SVG): interpolation is only supported
1369 between: gradient to gradient and color to color. They then
1370 work as above.
1371 </li>
1372 <li id="animtype-simple-list">
1373 <strong>simple list</strong> of other types:
1374 If the lists have the same number of items,
1375 and each pair of values can be interpolated,
1376 each item in the list is interpolated using
1377 the rules given for those types.
1378 Otherwise the values are not interpolable.
1379 </li>
1380 <li id="animtype-repeatable-list">
1381 <strong>repeatable list</strong> of other types:
1382 The result list has a length that is the least common multiple
1383 of the lengths of the input lists.
1384 Each item in the result is the interpolation of the value
1385 from each input list repeated to the length of the result list.
1386 If a pair of values cannot be interpolated, then the lists
1387 are not interpolable.
1388 <span class="note">
1389 The repeatable list concept ensures that a list that is
1390 conceptually repeated to a certain length (as
1391 'background-origin' is repeated to the length of the
1392 'background-image' list) or repeated infinitely will
1393 smoothly transition between any values, and so that the
1394 computed value will properly represent the result (and
1395 potentially be inherited correctly).
1396 </span>
1397 </li>
1398 </ul>
1400 <p>Future specifications may define additional types that can
1401 be animated.</p>
1403 <p>See the definition of 'transition-property' for how animation
1404 of shorthand properties and the ''all'' value is applied to any
1405 properties (in the shorthand) that can be animated.</p>
1407 <h3 id="step-types">Animation in steps of other property types</h3>
1409 <p>
1410 When interpolating between two values that cannot be interpolated,
1411 <var>V</var><sub>start</sub> and <var>V</var><sub>end</sub>,
1412 interpolation is done using the output <var>p</var> of the timing function.
1413 If <var>p</var> is less than 0.5, then the
1414 result of the interpolation is
1415 <var>V</var><sub>start</sub>;
1416 if <var>p</var> is greater than or equal to 0.5, then the
1417 result of the interpolation is
1418 <var>V</var><sub>end</sub>.
1419 </p>
1421 <p class="note" id="discrete-interpolation-at-risk">
1422 This is a recent change to which implementations have
1423 not yet updated. (Prior to the change CSS Transitions
1424 and CSS Animations did not run on such changes.) It's
1425 possible that it won't be compatible with existing Web content.
1426 If that is the case, the problem may be mitigated by restricting
1427 this behavior only to CSS Animations (and not to CSS Transitions),
1428 and/or restricting it to step timing functions.
1429 </p>
1431 <h2 id="animatable-properties"><span id="animatable-properties-">
1432 Animatable properties
1433 </span></h2>
1435 <!--
1436 As resolved in
1437 http://lists.w3.org/Archives/Public/www-style/2011Sep/0497.html
1438 -->
1440 <p>The definition of each CSS property defines
1441 when the values of that property can be interpolated
1442 by referring to the definitions of property types
1443 in the <a href="#animatable-types">previous section</a>.
1444 The animated value is interpolated from the from and to values when
1445 both the from and the to values of the property have the type described.
1446 (When a composite type such as "length, percentage, or calc" is listed,
1447 this means that both values must fit into that composite type.)
1448 When multiple types are listed in the form "either A or B",
1449 both values must be of the same type to be interpolable.</p>
1451 <p>Otherwise, since the from and to values cannot be interpolated,
1452 the animation is done <a href="#step-types">in a single step</a>.</p>
1454 <p>The 'transition-*' properties defined in this specification do
1455 not undergo transitions.</p>
1457 <p>For properties that exist at the time this specification was
1458 developed, this specification defines how they are
1459 animated. However, future CSS specifications may define
1460 additional properties, additional values for existing properties,
1461 or additional animation behavior of existing values. In order to
1462 describe new animation behaviors and to have the definition of
1463 animation behavior in a more appropriate location, future CSS
1464 specifications should include an "Animatable:" line in the summary
1465 of the property's definition (in addition to the other lines
1466 described in [[CSS21]], <a
1467 href="https://www.w3.org/TR/CSS21/about.html#property-defs">section
1468 1.4.2</a>). This line should say "no" to indicate that a property
1469 cannot be animated or should reference an animation behavior
1470 (which may be one of the behaviors in the <a
1471 href="#animation-of-property-types-">Animation of property
1472 types</a> section above, or may be a new behavior) to define how
1473 the property animates. Such definitions override those given in
1474 this specification.</p>
1476 <p class="issue">
1477 It no longer makes sense for this line to be called
1478 "Animatable". It should probably be renamed to "Interpolation",
1479 and the "no" value renamed to "discrete" or "in steps".
1480 </p>
1482 <h3 id="animatable-css"><span id="properties-from-css-">
1483 Properties from CSS
1484 </span></h3>
1486 <p>
1487 The following definitions define the animation behavior for
1488 properties in CSS Level 2 Revision 1 ([[CSS21]]) and in Level 3 of
1489 the CSS Color Module ([[CSS3COLOR]]).
1490 </p>
1492 <table class="animatable-properties">
1493 <tr>
1494 <th>Property Name</th>
1495 <th>Type</th>
1496 </tr>
1497 <tr>
1498 <td>'background-color'</td><td>as <a href="#animtype-color">color</a></tr>
1499 <tr>
1500 <td>'background-position'</td><td>as <a href="#animtype-repeatable-list">repeatable list</a> of <a href="#animtype-simple-list">simple list</a> of <a href="#animtype-lpcalc">length, percentage, or calc</a></td>
1501 </tr>
1502 <tr>
1503 <td>'border-bottom-color'</td><td>as <a href="#animtype-color">color</a></td>
1504 </tr>
1505 <tr>
1506 <td>'border-bottom-width'</td><td>as <a href="#animtype-length">length</a></td>
1507 </tr>
1508 <tr>
1509 <td>'border-left-color'</td><td>as <a href="#animtype-color">color</a></td>
1510 </tr>
1511 <tr>
1512 <td>'border-left-width'</td><td>as <a href="#animtype-length">length</a></td>
1513 </tr>
1514 <tr>
1515 <td>'border-right-color'</td><td>as <a href="#animtype-color">color</a></td>
1516 </tr>
1517 <tr>
1518 <td>'border-right-width'</td><td>as <a href="#animtype-length">length</a></td>
1519 </tr>
1520 <tr>
1521 <td>'border-spacing'</td><td>as <a href="#animtype-simple-list">simple list</a> of <a href="#animtype-length">length</a></td>
1522 </tr>
1523 <tr>
1524 <td>'border-top-color'</td><td>as <a href="#animtype-color">color</a></td>
1525 </tr>
1526 <tr>
1527 <td>'border-top-width'</td><td>as <a href="#animtype-length">length</a></td>
1528 </tr>
1529 <tr>
1530 <td>'bottom'</td><td>as <a href="#animtype-lpcalc">length, percentage, or calc</a></td>
1531 </tr>
1532 <tr>
1533 <td>'clip'</td><td>as <a href="#animtype-rect">rectangle</a></td>
1534 </tr>
1535 <tr>
1536 <td>'color'</td><td>as <a href="#animtype-color">color</a></td>
1537 </tr>
1538 <tr>
1539 <td>'font-size'</td><td>as <a href="#animtype-length">length</a></td>
1540 </tr>
1541 <tr>
1542 <td>'font-weight!!property'</td><td>as <a href="#animtype-font-weight">font weight</a></td>
1543 </tr>
1544 <tr>
1545 <td>'height'</td><td>as <a href="#animtype-lpcalc">length, percentage, or calc</a></td>
1546 </tr>
1547 <tr>
1548 <td>'left'</td><td>as <a href="#animtype-lpcalc">length, percentage, or calc</a></td>
1549 </tr>
1550 <tr>
1551 <td>'letter-spacing'</td><td>as <a href="#animtype-length">length</a></td>
1552 </tr>
1553 <tr>
1554 <td>'line-height'</td><td>as either <a href="#animtype-number">number</a> or <a href="#animtype-length">length</a></td>
1555 </tr>
1556 <tr>
1557 <td>'margin-bottom'</td><td>as <a href="#animtype-length">length</a></td>
1558 </tr>
1559 <tr>
1560 <td>'margin-left'</td><td>as <a href="#animtype-length">length</a></td>
1561 </tr>
1562 <tr>
1563 <td>'margin-right'</td><td>as <a href="#animtype-length">length</a></td>
1564 </tr>
1565 <tr>
1566 <td>'margin-top'</td><td>as <a href="#animtype-length">length</a></td>
1567 </tr>
1568 <tr>
1569 <td>'max-height'</td><td>as <a href="#animtype-lpcalc">length, percentage, or calc</a></td>
1570 </tr>
1571 <tr>
1572 <td>'max-width'</td><td>as <a href="#animtype-lpcalc">length, percentage, or calc</a></td>
1573 </tr>
1574 <tr>
1575 <td>'min-height'</td><td>as <a href="#animtype-lpcalc">length, percentage, or calc</a></td>
1576 </tr>
1577 <tr>
1578 <td>'min-width'</td><td>as <a href="#animtype-lpcalc">length, percentage, or calc</a></td>
1579 </tr>
1580 <tr>
1581 <td>'opacity'</td><td>as <a href="#animtype-number">number</a></td>
1582 </tr>
1583 <tr>
1584 <td>'outline-color'</td><td>as <a href="#animtype-color">color</a></td>
1585 </tr>
1586 <tr>
1587 <td>'outline-width'</td><td>as <a href="#animtype-length">length</a></td>
1588 </tr>
1589 <tr>
1590 <td>'padding-bottom'</td><td>as <a href="#animtype-length">length</a></td>
1591 </tr>
1592 <tr>
1593 <td>'padding-left'</td><td>as <a href="#animtype-length">length</a></td>
1594 </tr>
1595 <tr>
1596 <td>'padding-right'</td><td>as <a href="#animtype-length">length</a></td>
1597 </tr>
1598 <tr>
1599 <td>'padding-top'</td><td>as <a href="#animtype-length">length</a></td>
1600 </tr>
1601 <tr>
1602 <td>'right'</td><td>as <a href="#animtype-lpcalc">length, percentage, or calc</a></td>
1603 </tr>
1604 <tr>
1605 <td>'text-indent'</td><td>as <a href="#animtype-lpcalc">length, percentage, or calc</a></td>
1606 </tr>
1607 <tr>
1608 <td>'text-shadow'</td><td>as <a href="#animtype-shadow-list">shadow list</a></td>
1609 </tr>
1610 <tr>
1611 <td>'top'</td><td>as <a href="#animtype-lpcalc">length, percentage, or calc</a></td>
1612 </tr>
1613 <tr>
1614 <td>'vertical-align'</td><td>as <a href="#animtype-length">length</a></td>
1615 </tr>
1616 <tr>
1617 <td>'visibility'</td><td>as <a href="#animtype-visibility">visibility</a></td>
1618 </tr>
1619 <tr>
1620 <td>'width'</td><td>as <a href="#animtype-lpcalc">length, percentage, or calc</a></td>
1621 </tr>
1622 <tr>
1623 <td>'word-spacing'</td><td>as <a href="#animtype-length">length</a></td>
1624 </tr>
1625 <tr>
1626 <td>'z-index'</td><td>as <a href="#animtype-integer">integer</a></td>
1627 </tr>
1628 </table>
1630 <h3 id="animatable-svg"><span id="properties-from-svg-">
1631 Properties from SVG
1632 </span></h3>
1634 <p>
1635 All properties defined as animatable in the SVG specification, provided
1636 they are one of the property types listed above.
1637 </p>
1639 <!-- <table>
1640 <tr>
1641 <th>Property Name</th><th>Type</th>
1642 </tr>
1643 <tr>
1644 <td>stop-color</td><td>as <a href="#animtype-color">color</a></td>
1645 </tr>
1646 <tr>
1647 <td>stop-opacity</td><td>as <a href="#animtype-number">number</a></td>
1648 </tr>
1649 <tr>
1650 <td>fill</td><td>as <a href="#animtype-paintserver">paint server</a></td>
1651 </tr>
1652 <tr>
1653 <td>fill-opacity</td><td>as <a href="#animtype-number">number</a></td>
1654 </tr>
1655 <tr>
1656 <td>stroke</td><td>as <a href="#animtype-paintserver">paint server</a></td>
1657 </tr>
1658 <tr>
1659 <td>stroke-dasharray</td><td>as <a href="#animtype-repeatable-list">repeatable list</a> of <a href="#animtype-number">number</a></td>
1660 </tr>
1661 <tr>
1662 <td>stroke-dashoffset</td><td>as <a href="#animtype-number">number</a></td>
1663 </tr>
1664 <tr>
1665 <td>stroke-miterlimit</td><td>as <a href="#animtype-number">number</a></td>
1666 </tr>
1667 <tr>
1668 <td>stroke-opacity</td><td>as <a href="#animtype-number">number</a></td>
1669 </tr>
1670 <tr>
1671 <td>stroke-width</td><td>as <a href="#animtype-number">number</a></td>
1672 </tr>
1673 <tr>
1674 <td>viewport-fill</td><td>as <a href="#animtype-color">color</a></td>
1675 </tr>
1676 <tr>
1677 <td>viewport-fill-opacity</td><td>as <a href="#animtype-color">color</a></td>
1678 </tr>
1679 </table> -->
1681 Security Considerations {#security}
1682 ===================================
1684 <em>This section is not normative.</em>
1686 The security implications of this specification are limited
1687 because it doesn't allow Web content to do things
1688 that it could not do before.
1689 Rather, it allows things that could previously be done with script
1690 to be done declaratively,
1691 and it ways that implementations can optimize (for frame rate and
1692 CPU usage).
1694 One of the major categories of optimizations
1695 that implementations can make is implementing animation
1696 of certain high-value properties (such as 'transform' and 'opacity')
1697 run on a browser's compositor thread or process
1698 without updating style or layout on the main Web content thread
1699 unless up-to-date style data are needed.
1700 This optimization often requires allocations of graphics memory
1701 to display the contents of the element being animated.
1702 Implementations should take care to ensure that Web content
1703 cannot trigger unsafe out-of-memory handling
1704 by using large numbers of animations
1705 or animations on elements covering large areas
1706 (where large may be defined in terms of pre-transform or post-transform size).
1708 Privacy Considerations {#privacy}
1709 =================================
1711 <em>This section is not normative.</em>
1713 As for security, the privacy considerations of this specification are limited
1714 because it does not allow Web content to do things that it could not do before.
1716 This specification may provide additional mechanisms that help to determine
1717 characteristics of the user's hardware or software.
1718 However, ability to determine performance characteristics of the user's
1719 hardware or software is common to many Web technologies,
1720 and this specification does not introduce new capabilities.
1722 As described in [[#accessibility]],
1723 implementations may provide mitigations to help users with disabilities.
1724 These mitigations are likely to be detectable by Web content,
1725 which means that users who would benefit from these mitigations
1726 may face a tradeoff between keeping their disability private from
1727 the Web content or benefiting from the mitigation.
1729 Accessibility Considerations {#accessibility}
1730 =============================================
1732 <em>This section is not normative.</em>
1734 Motion {#accessibility-motion}
1735 ------------------------------
1737 This specification provides declarative mechanisms for animations
1738 that previously needed to be done using script.
1739 Providing a declarative mechanism has multiple effects:
1740 it makes such animations easier to make and thus likely to be more common,
1741 but it also makes it easier for user agents to modify those animations
1742 if such modifications are needed to meet a user's accessibility needs.
1744 Thus, users who are sensitive to movement,
1745 or who require additional time to read or understand content,
1746 may benefit from user agent features that allow
1747 animations to be disabled or slowed down.
1748 (But see [[#privacy]] for information on the privacy implications
1749 of such mitigations.)
1751 User agent implementors should be aware that Web content
1752 may depend on the firing of <a href="#transition-events">transition events</a>,
1753 so implementations of such mitigations may wish to fire transition events
1754 even if the transitions were not run as continuous animations.
1755 However, it is probably poor practice for Web content to depend on
1756 such events to function correctly.
1758 Cascade {#accessibility-cascade}
1759 --------------------------------
1761 The CSS <a>cascade</a> is a general mechanism in CSS
1762 that allows user needs to interact with author styles.
1763 This specification interacts with the cascade,
1764 but since it only allows animation between values
1765 that result from the existing cascade rules,
1766 it does not interfere with the user's ability to force
1767 CSS properties to have particular values.
1769 The cascade also allows users to disable transitions entirely
1770 by overriding the transition properties.
1773 <h2 id="changes">Changes since Working Draft of 19 November 2013</h2>
1775 <p>The following are the substantive changes made since the
1776 <a href="https://www.w3.org/TR/2013/WD-css3-transitions-20131119/">Working Draft
1777 dated 19 November 2013</a>:</p>
1779 <ul>
1780 <li>Values that cannot be interpolated are transitioned when the timing function crosses its midpoint, instead of not running transitions and changing immediately.</li>
1781 <li>Canceling and interrupting of running transitions is defined much more precisely. This includes the after-change style no longer including styles from CSS Transitions.</li>
1782 <li>Completion of transitions is defined somewhat more precisely.</li>
1783 <li>The transitionend event is no longer cancelable. This is since it has no default action, so canceling it would have no meaning. It also matches the animation events.</li>
1784 <li>The interpolation of ''shadow/inset'' values on shadow lists is no longer backwards.</li>
1785 <li>A [[#conformance]] section, [[#security]] section, [[#privacy]] section, [[#accessibility]] section, and [[#idl-index]] have been added</li>
1786 <li>The identifiers accepted by 'transition-property' are defined in terms of <<custom-ident>>.</li>
1787 <li>Define a little bit more about when changes to computed values happen, by saying at least that implementations must not update the effects of computed values without actually updating computed values.</li>
1788 </ul>
1790 <p>For more details on these changes, see the version control <a href="https://hg.csswg.org/drafts/log/tip/css-transitions/Overview.bs">change log since 2015 January 26</a> and the <a href="https://hg.csswg.org/drafts/log/tip/css-transitions/Overview.src.html">change log from 2013 March 28 to 2015 January 26</a>.</p>
1792 <p>For changes in earlier working drafts:</p>
1794 <ol>
1795 <li>see the <a href="https://www.w3.org/TR/2013/WD-css3-transitions-20131119/#changes">changes section in the 19 November 2013 Working Draft</a>
1796 <li>see the <a href="https://www.w3.org/TR/2013/WD-css3-transitions-20130212/ChangeLog">the ChangeLog</a> for changes in previous working drafts
1797 <li>For more details on these changes, see the version control change logs, which are split in three parts because of file renaming: <a href="https://hg.csswg.org/drafts/log/tip/css-transitions/Overview.bs">change log since 2015 January 26</a>, <a href="https://hg.csswg.org/drafts/log/tip/css-transitions/Overview.src.html">change log from 2013 March 28 to 2015 January 26</a>, <a href="https://hg.csswg.org/drafts/log/tip/css3-transitions/Overview.src.html">change log before 2013 March 28</a>.
1798 </ol>
1800 <h2 id="acknowledgments">Acknowledgments</h2>
1802 <p>Thanks especially to the feedback from
1803 Tab Atkins,
1804 Carine Bournez,
1805 Aryeh Gregor,
1806 Vincent Hardy,
1807 Anne van Kesteren,
1808 Cameron McCormack,
1809 Alex Mogilevsky,
1810 Jasper St. Pierre,
1811 Estelle Weyl,
1812 and all the rest of the
1813 <a href="http://lists.w3.org/Archives/Public/www-style/">www-style</a> community.</p>