Abstract

CSS Transitions allows property changes in CSS values to occur smoothly over a specified duration.

Status of this document

This section describes the status of this document at the time of its publication. Other documents may supersede this document. A list of current W3C publications and the latest revision of this technical report can be found in the W3C technical reports index at http://www.w3.org/TR/.

Publication as a Working Draft does not imply endorsement by the W3C Membership. This is a draft document and may be updated, replaced or obsoleted by other documents at any time. It is inappropriate to cite this document as other than work in progress.

The (archived) public mailing list www-style@w3.org (see instructions) is preferred for discussion of this specification. When sending e-mail, please put the text “css3-transitions” in the subject, preferably like this: “[css3-transitions] …summary of comment…”

This document was produced by the CSS Working Group (part of the Style Activity).

This document was produced by a group operating under the 5 February 2004 W3C Patent Policy. W3C maintains a public list of any patent disclosures made in connection with the deliverables of the group; that page also includes instructions for disclosing a patent. An individual who has actual knowledge of a patent which the individual believes contains Essential Claim(s) must disclose the information in accordance with section 6 of the W3C Patent Policy.

This document 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.

Table of Contents

1. Introduction

This section is not normative.

This document introduces new CSS features to enable implicit transitions, which describe how CSS properties can be made to change smoothly from one value to another over a given duration.

2. Transitions

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.

For example, suppose that transitions of one second have been defined on the ‘left’ and ‘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.

Transitions of ‘left’ and ‘background-color’

Transitions are a presentational effect. The computed value of a property transitions over time from the old value to the new value. Therefore if a script queries the computed style of a property as it is transitioning, it will see an intermediate value that represents the current animated value of the property.

Only animatable CSS properties can be transitioned. See the table at the end of this document for a list of properties that are animatable.

The transition for a property is defined using a number of new properties. For example:

  div {
    transition-property: opacity;
    transition-duration: 2s;
  }
  

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:

  div {
    transition-property: opacity, left;
    transition-duration: 2s, 4s;
  }

  

In the case where the lists of values in transition properties do not have the same length, the length of the ‘transition-property’ list determines the number of items in each list examined when starting transitions. The lists are matched up from the first value: excess values at the end are not used. If one of the other properties doesn't have enough comma-separated values to match the number of values of ‘transition-property’, the UA must calculate its used value by repeating the list of values until there are enough. This truncation or repetition does not affect the computed value. Note: This is analogous to the behavior of the ‘background-*’ properties, with ‘background-image’ analogous to ‘transition-property’.

      div {
        transition-property: opacity, left, top, width;
        transition-duration: 2s, 1s;
      }
      

While authors can use transitions to create dynamically changing content, dynamically changing content can lead to seizures in some users. For information on how to avoid content that can lead to seizures, see Guideline 2.3: Seizures: Do not design content in a way that is known to cause seizures ([WCAG20]).

2.1. The ‘transition-property’ Property

The ‘transition-property’ property specifies the name of the CSS property to which the transition is applied.

A value of ‘none’ means that no property will transition. Otherwise, a list of properties to be transitioned, or the keyword ‘all’ which indicates that all properties are to be transitioned, is given.

If one of the identifiers listed is not a recognized property name or is not an animatable property, the implementation must still start transitions on the animatable properties in the list using the duration, delay, and timing function at their respective indices in the lists for ‘transition-duration’, ‘transition-delay’, and ‘transition-timing-function’. In other words, unrecognized or non-animatable properties must be kept in the list to preserve the matching of indices.

The keywords ‘none’, ‘inherit’, and ‘initial’ are not permitted as items within a list of more that one identifier; any list that uses them is syntactically invalid. In other words, the <IDENT> production in <single-transition-property> matches any identifier other than these three keywords.

For the keyword ‘all’, or if one of the identifiers listed is a shorthand property, implementations must start transitions for any of its longhand sub-properties that are animatable (or, for ‘all’, all animatable properties), using the duration, delay, and timing function at the index corresponding to the shorthand.

If a property is specified multiple times in the value of ‘transition-property’ (either on its own, via a shorthand that contains it, or via the ‘all’ value), then the transition that starts uses the duration, delay, and timing function at the index corresponding to the last item in the value of ‘transition-property’ that calls for animating that property.

Note: The ‘all’ value and ‘all’ shorthand property work in similar ways, so the ‘all’ value is just like a shorthand that covers all properties.

2.2. The ‘transition-duration’ Property

The ‘transition-duration’ property defines the length of time that a transition takes.

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.

2.3. The ‘transition-timing-function’ Property

The ‘transition-timing-function’ property describes how the intermediate values used during a transition will be calculated. It allows for a transition to change speed over its duration. These effects are commonly called easing functions. In either case, a mathematical function that provides a smooth curve is used.

Timing functions are either defined as a stepping function or a cubic Bézier curve. The timing function takes as its input the current elapsed percentage of the transition duration and outputs the percentage of the way the transition is from its start value to its end value. How this output is used is defined by the interpolation rules for the value type.

A stepping function is defined by a number that divides the domain of operation into equally sized intervals. Each subsequent interval is a equal step closer to the goal state. The function also specifies whether the change in output percentage happens at the start or end of the interval (in other words, if 0% on the input percentage is the point of initial change).