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