CSS Will Change Module Level 1

Editor’s Draft, 5 May 2014

This version:
http://tabatkins.github.io/specs/css-will-change/
Editor’s Draft:
http://tabatkins.github.io/specs/css-will-change/
Test Suite:
None Yet
Editors:
Tab Atkins Jr. (Google Inc.)
This Document Is Obsolete and Has Been Replaced

This specification is obsolete and has been replaced by the document at http://dev.w3.org/csswg/css-will-change/. Do not attempt to implement this specification. Do not refer to this specification except as a historical artifact.


Abstract

This document defines the will-change property, which allows an author to inform the UA ahead of time of what kinds of changes they are likely to make to an element. This allows the UA to optimize how they handle the element ahead of time, performing potentially-expensive work preparing for an animation before the animation actually begins.

Table of Contents

1 Introduction

Modern CSS renderers perform a number of complex optimizations in order to render webpages quickly and efficiently. Unfortunately, employing these optimizations often has a non-trivial start-up cost, which can have a negative impact on the responsiveness of a page.

For example, when using CSS 3D Transforms to move an element around the screen, the element and its contents might be promoted to a “layer”, where they can render independently from the rest of the page and be composited in later. This isolates the rendering of the content so that the rest of the page doesn’t have to be rerendered if the element’s transform is the only thing that changes between frames, and often provides significant speed benefits.

However, setting up the element in a fresh layer is a relatively expensive operation, which can delay the start of a transform animation by a noticeable fraction of a second.

The will-change property defined in this specification allows an author to declare ahead-of-time what properties are likely to change in the future, so the UA can set up the appropriate optimizations some time before they’re needed. This way, when the actual change happens, the page updates in a snappy manner.

2 Hinting at Future Behavior: the will-change property

Name:will-change
Value:auto | <animateable-feature>#
Initial:auto
Applies to:all elements
Inherited:no
Media:all
Computed value:specified value
Percentages:n/a
<animateable-feature> = scroll-position | contents | <custom-ident>

The will-change property provides a rendering hint to the user agent, stating what kinds of changes the author expects to perform on the element. This allows the user agent to perform ahead-of-time any optimizations necessary for rendering those changes smoothly, avoiding “jank” when the author does begin changing or animating that feature.

Values have the following meanings:

auto
Expresses no particular intent.
scroll-position
Indicates that the author expects to animate or change the scroll position of the element in the near future.
contents
Indicates that the author expects to animate or change something about the element’s contents in the near future.
<custom-ident>
Indicates that the author expects to animate or change the property with the given name on the element in the near future.

The <custom-ident> production used here excludes the keywords will-change, none, all, auto, scroll-position, and contents, in addition to the keywords normally excluded from <custom-ident>.

Note: Note that most properties will have no effect when specified, as the user agent doesn’t perform any special optimizations for changes in most properties. It is still safe to specify them, though; it’ll simply have no effect.

If any non-initial value of a property would create a stacking context on the element, specifying that property in will-change must create a stacking context on the element.

If any non-initial value of a property would cause the element to generate a containing block for fixed-position elements, specifying that property in will-change must cause the element to generate a containing block for fixed-position elements.

If a non-initial value of a property would cause rendering differences on the element (such as using a different anti-aliasing strategy for text), the user agent should use that alternate rendering when the property is specified in will-change, to avoid sudden rendering differences when the property is eventually changed.

For example, setting opacity to any value other than 1 creates a stacking context on the element. Thus, setting will-change: opacity also creates a stacking context, even if opacity is currently still equal to 1.

The will-change property has no direct effect on the element it is specified on, beyond the creation of stacking contexts and containing blocks as specified above. It is solely a rendering hint to the user agent, allowing it set up potentially-expensive optimizations for certain types of changes before the changes actually start occurring.

Conformance

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.

References

Normative References

[RFC2119]
S. Bradner. Key words for use in RFCs to Indicate Requirement Levels. URL: http://www.ietf.org/rfc/rfc2119.txt

Informative References

Index

Property index

NameValueInitialApplies toInh.%agesMediaComputed value
will-changeauto | <animateable-feature>#autoall elementsnon/aallspecified value