CSS Transitions Level 2

Editor’s Draft,

This version:
https://drafts.csswg.org/css-transitions-2/
Issue Tracking:
Bugzilla bugs for all levels
Inline In Spec
GitHub Issues
Editor:
(Mozilla)

Abstract

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

CSS is a language for describing the rendering of structured documents (such as HTML and XML) on screen, on paper, in speech, etc.

Status of this document

This is a public copy of the editors’ draft. It is provided for discussion only and may change at any moment. Its publication here does not imply endorsement of its contents by W3C. Don’t cite this document other than as work in progress.

GitHub Issues are preferred for discussion of this specification. When filing an issue, please put the text “css-transitions-2” in the title, preferably like this: “[css-transitions-2] …summary of comment…”. All issues and comments are archived, and there is also a historical archive.

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 governed by the 1 March 2017 W3C Process Document.

1. Delta specification

This is a delta specification, meaning that it currently contains only the differences from CSS Transitions Level 1 [CSS3-TRANSITIONS]. Once the Level 1 specification is closer to complete, it will be merged with the additions here into a complete level 2 specification.

2. Starting of transitions

Associated with each top-level browsing context is a current transition generation that is incremented on each style change event.

Each time a new transition is generated, the current value of the (already incremented) current transition generation is stored as the transition’s transition generation.

2.1. The transition property name

Although the transition-property may specify shorthand properties and the all keyword, individual transitions are generated for each longhand sub-property that is animatable. The expanded transition property name of a transition is the name of the longhand sub-property for which the transition was generated (e.g. border-left-width).

2.2. Owning element

The owning element of a transition refers to the element or pseudo-element to which the transition-property property was applied that generated the animation.

If a transition was generated directly by script (e.g. using the CSSTransition constructor) then it has no owning element.

If a transition generated using the markup defined in this specification is later disassociated from that markup because it is cancelled or replaced by a newer transition, the animation is disassociated from its owning element (that is, it has no owning element from that point forwards).

Define the above more precisely once we rewrite firing of transitions in terms of Web Animations concepts (specifically when we spell out when we cancel an animation).

2.3. Animation composite order

Animations generated from the markup and interfaces (e.g. the CSSTransition constructor) defined in this specification have an animation class of ‘CSS Transition’.

CSS Transitions have an earlier composite order that CSS Animations and animations without a specific animation class.

Within the set of CSS Transitions, two animations A and B are sorted in composite order (first to last) as follows:

  1. If neither A nor B has an owning element, sort based on their relative position in the global animation list.

  2. Otherwise, if only one of A or B has an owning element, let the animation with an owning element sort first.

  3. Otherwise, if the owning element of A and B differs, sort A and B by tree order of their corresponding owning elements. With regard to pseudo-elements, the sort order is as follows:

    • element

    • ::before

    • ::after

    • element children

  4. Otherwise, if A and B have different transition generation values, sort by their corresponding transition generation in ascending order.

  5. Otherwise, sort A and B in ascending order by the Unicode codepoints that make up the expanded transition property name of each transition (i.e. without attempting case conversion and such that ‘-moz-column-width’ sorts before ‘column-width’).

Transitions generated using the markup defined in this specification are not added to the global animation list when they are created. Instead, these animations are appended to the global animation list at the first moment when they transition out of the idle play state after being disassociated from their owning element. Transitions that have been disassociated from their owning element but are still idle do not have a defined composite order.

Note, this behavior relies on the fact that disassociating a transition from its owning element always causes it to enter (or remain) in the idle play state.

Transitions created using the CSSTransition constructor are appended to the global animation list at the moment they are constructed.

3. Transition Events

3.1. Event dispatch

Note, this is a more general description of event dispatch than that of CSS Transitions Level 1 [CSS3-TRANSITIONS] since it must account for the possibility of animations being seeked or reversed using the Web Animations API [WEB-ANIMATIONS]. Furthermore, it is possible using the Web Animations API to substitute the transition effect with an entirely different effect with properties not normally used with transitions (e.g. an effect that repeats multiple times) and hence this section provides a generic definition that accounts for the full complexity of the Web Animations model.

To avoid firing redundant events, the set of events to dispatch is based on comparing the phase of the transition in the previous sample (animation frame) to its current state.

The transition phase of a transition is initially ‘idle’ and is updated on each sample according to the first matching condition from below:

If the transition has no target effect,
The transition phase is set according to the first matching condition from below:
If the transition has an unresolved current time,
The transition phase is ‘idle’.
If the transition has a current time < 0,
The transition phase is ‘before’.
Otherwise,
The transition phase is ‘after’.
If the transition is pending and its phase was previously ‘idle’ or ‘pending’,
The transition phase is ‘pending’.
Otherwise,
The transition phase is the phase of its target effect.

For calculating the elapsedTime of each event, the following definitions are used:

In the above formulae, references to the start delay, active duration, current iteration, iteration start, and iteration duration of a transition should be understood to refer to the corresponding properties of the transition’s target effect.

Each time an animation is sampled, the events to dispatch are determined by comparing the transition phase before and after the sample as follows:

Change Events dispatched Elapsed time (ms)
idle → pending or before transitionrun interval start
idle → active ٭ transitionrun interval start
transitionstart
idle → after ٭ transitionrun interval start
transitionstart
transitionend interval end
pending or before → active transitionstart interval start
pending or before → after ٭ transitionstart interval start
transitionend interval end
active → after transitionend interval end
active → before transitionend interval start
after → active transitionstart interval end
after → before ٭ transitionstart interval end
transitionend interval start
not idle and not after → idle transitioncancel The active time of the animation at the moment it was cancelled calculated using a fill mode of both.

٭ Where multiple events are listed for a state change, all events are dispatched in the order listed and in immediate succession.

Since the elapsed time defined in the table and procedure above is expressed in milliseconds, it must be divided by 1,000 to produce a value in seconds before being assigned to the elapsedTime member of the TransitionEvent.

The above state transition chart ensures that, with the exception of transitions that are paused or have an infinite running time, the following invariants hold:

The typical sequences of events, then, are as follows:

4. DOM Interfaces

4.1. The CSSTransition interface

interface CSSTransition : Animation {
  readonly attribute CSSOMString transitionProperty;
};
transitionProperty, of type CSSOMString, readonly

The expanded transition property name of this transition.

This interface needs a constructor. Perhaps something like the following,

[Constructor (Animatable? target,
              CSSOMString transitionProperty,
              any transitionValue,
              optional (unrestricted double or KeyframeEffectOptions) options),
 Constructor (Animatable? target,
              CSSOMString transitionProperty,
              any transitionValue,
              (unrestricted double or KeyframeEffectOptions) options,
              AnimationTimeline? timeline)]
partial interface CSSTransition { };

Using any as the type for transitionValue would allow the following usage:

var transition = new CSSTransition(elem, 'opacity', 1, 2000);
transition.play();

The above example, however, is not equivalent to triggering a transition. It has the following differences:

It is unclear how much we should extend the CSSTransition constructor to overcome the above limitations so that it can be used to generate transitions programmatically, or whether we should introduce a separate helper method such as has been suggested elsewhere.

4.2. Requirements on pending style changes

Various operations may affect the computed values of properties on elements. User agents may, as an optimization, defer recomputing these values until it becomes necessary. However, all operations included in programming interface defined in this specification, as well as those operations defined in Web Animations [WEB-ANIMATIONS] that may return objects defined by this specification, must produce a result consistent with having fully processed any such pending changes to computed values.

As an example, in the following code fragment, when the specified value of elem’s opacity property is updated, a user agent may defer recalculating the computed value of the animation property.

The first time this occurs, calling getComputedStyle(elt) and subsequently accessing the opacity property of the result will cause the user agent to recompute the value of opacity.

After the opacity property is updated a second time, the getAnimations() method is called on elem. This method is specified by Web Animations and can return CSSTransition objects as defined in this specification. Hence, as result of the requirements in this section, the user agent must apply any pending style changes thus generating a new CSSTransition for the opacity property before returning its result.

elem.style.transition = 'opacity 100s';
elem.style.opacity = '0';
window.getComputedStyle(elem).opacity; // 0
elem.style.opacity = '1';
elem.getAnimations()[0].transitionProperty // 'opacity'

5. Issues commonly raised as issues with previous levels

These issues were commonly reported issues with the previous level of the specification.

More powerful timing function syntax is a common request from developers. See, for example: 2013 message or 2015 thread.

Developers frequently have to trigger style flushes in order to force transitions to start. It would be good to have an API that would avoid this requirement. See, for example, 2011 proposal.

6. Issues deferred from previous levels of the spec

These issues were in previous levels of the specification, but may not turn out to be important in this level either.

We may ultimately want to support a keypath syntax for the transition-property property. A keypath syntax would enable different transitions to be specified for components of a property. For example the blur of a shadow could have a different transition than the color of a shadow.

Conformance

Document conventions

Conformance requirements are expressed with a combination of descriptive assertions and RFC 2119 terminology. The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in the normative parts of this document are to be interpreted as described in RFC 2119. However, for readability, these words do not appear in all uppercase letters in this specification.

All of the text of this specification is normative except sections explicitly marked as non-normative, examples, and notes. [RFC2119]

Examples in this specification are introduced with the words “for example” or are set apart from the normative text with class="example", like this:

This is an example of an informative example.

Informative notes begin with the word “Note” and are set apart from the normative text with class="note", like this:

Note, this is an informative note.

Advisements are normative sections styled to evoke special attention and are set apart from other normative text with <strong class="advisement">, like this: UAs MUST provide an accessible alternative.

Conformance classes

Conformance to this specification is defined for three conformance classes:

style sheet
A CSS style sheet.
renderer
A UA that interprets the semantics of a style sheet and renders documents that use them.
authoring tool
A UA that writes a style sheet.

A style sheet is conformant to this specification if all of its statements that use syntax defined in this module are valid according to the generic CSS grammar and the individual grammars of each feature defined in this module.

A renderer is conformant to this specification if, in addition to interpreting the style sheet as defined by the appropriate specifications, it supports all the features defined by this specification by parsing them correctly and rendering the document accordingly. However, the inability of a UA to correctly render a document due to limitations of the device does not make the UA non-conformant. (For example, a UA is not required to render color on a monochrome monitor.)

An authoring tool is conformant to this specification if it writes style sheets that are syntactically correct according to the generic CSS grammar and the individual grammars of each feature in this module, and meet all other conformance requirements of style sheets as described in this module.

Requirements for Responsible Implementation of CSS

The following sections define several conformance requirements for implementing CSS responsibly, in a way that promotes interoperability in the present and future.

Partial Implementations

So that authors can exploit the forward-compatible parsing rules to assign fallback values, CSS renderers must treat as invalid (and ignore as appropriate) any at-rules, properties, property values, keywords, and other syntactic constructs for which they have no usable level of support. In particular, user agents must not selectively ignore unsupported property values and honor supported values in a single multi-value property declaration: if any value is considered invalid (as unsupported values must be), CSS requires that the entire declaration be ignored.

Implementations of Unstable and Proprietary Features

To avoid clashes with future stable CSS features, the CSSWG recommends following best practices for the implementation of unstable features and proprietary extensions to CSS.

Implementations of CR-level Features

Once a specification reaches the Candidate Recommendation stage, implementers should release an unprefixed implementation of any CR-level feature they can demonstrate to be correctly implemented according to spec, and should avoid exposing a prefixed variant of that feature.

To establish and maintain the interoperability of CSS across implementations, the CSS Working Group requests that non-experimental CSS renderers submit an implementation report (and, if necessary, the testcases used for that implementation report) to the W3C before releasing an unprefixed implementation of any CSS features. Testcases submitted to W3C are subject to review and correction by the CSS Working Group.

Further information on submitting testcases and implementation reports can be found from on the CSS Working Group’s website at http://www.w3.org/Style/CSS/Test/. Questions should be directed to the public-css-testsuite@w3.org mailing list.

Index

Terms defined by this specification

Terms defined by reference

References

Normative References

[CSS-BACKGROUNDS-3]
CSS Backgrounds and Borders Module Level 3 URL: https://www.w3.org/TR/css3-background/
[CSS-CASCADE-4]
Elika Etemad; Tab Atkins Jr.. CSS Cascading and Inheritance Level 4. URL: https://www.w3.org/TR/css-cascade-4/
[CSS-TRANSITIONS-1]
CSS Transitions Module Level 1 URL: https://www.w3.org/TR/css3-transitions/
[CSS3-TRANSITIONS]
Dean Jackson; et al. CSS Transitions. URL: https://www.w3.org/TR/css3-transitions/
[CSSOM-1]
Simon Pieters; Glenn Adams. CSS Object Model (CSSOM). URL: https://www.w3.org/TR/cssom-1/
[DOM]
Anne van Kesteren. DOM Standard. Living Standard. URL: https://dom.spec.whatwg.org/
[RFC2119]
S. Bradner. Key words for use in RFCs to Indicate Requirement Levels. March 1997. Best Current Practice. URL: https://tools.ietf.org/html/rfc2119
[WEB-ANIMATIONS]
Brian Birtles; et al. Web Animations. URL: https://www.w3.org/TR/web-animations-1/
[WebIDL]
Cameron McCormack; Boris Zbarsky; Tobie Langel. Web IDL. URL: https://heycam.github.io/webidl/

Informative References

[CSS-ANIMATIONS-1]
CSS Animations Module Level 1 URL: https://www.w3.org/TR/css3-animations/
[CSS-COLOR-4]
Tab Atkins Jr.; Chris Lilley. CSS Color Module Level 4. URL: https://www.w3.org/TR/css-color-4/

IDL Index

interface CSSTransition : Animation {
  readonly attribute CSSOMString transitionProperty;
};

[Constructor (Animatable? target,
              CSSOMString transitionProperty,
              any transitionValue,
              optional (unrestricted double or KeyframeEffectOptions) options),
 Constructor (Animatable? target,
              CSSOMString transitionProperty,
              any transitionValue,
              (unrestricted double or KeyframeEffectOptions) options,
              AnimationTimeline? timeline)]
partial interface CSSTransition { };

Issues Index

Define the above more precisely once we rewrite firing of transitions in terms of Web Animations concepts (specifically when we spell out when we cancel an animation).

This interface needs a constructor. Perhaps something like the following,

[Constructor (Animatable? target,
              CSSOMString transitionProperty,
              any transitionValue,
              optional (unrestricted double or KeyframeEffectOptions) options),
 Constructor (Animatable? target,
              CSSOMString transitionProperty,
              any transitionValue,
              (unrestricted double or KeyframeEffectOptions) options,
              AnimationTimeline? timeline)]
partial interface CSSTransition { };

Using any as the type for transitionValue would allow the following usage:

var transition = new CSSTransition(elem, 'opacity', 1, 2000);
transition.play();

The above example, however, is not equivalent to triggering a transition. It has the following differences:

It is unclear how much we should extend the CSSTransition constructor to overcome the above limitations so that it can be used to generate transitions programmatically, or whether we should introduce a separate helper method such as has been suggested elsewhere.

More powerful timing function syntax is a common request from developers. See, for example: 2013 message or 2015 thread.

Developers frequently have to trigger style flushes in order to force transitions to start. It would be good to have an API that would avoid this requirement. See, for example, 2011 proposal.

We may ultimately want to support a keypath syntax for the transition-property property. A keypath syntax would enable different transitions to be specified for components of a property. For example the blur of a shadow could have a different transition than the color of a shadow.