will-change CSS property
Baseline
Widely available
This feature is well established and works across many devices and browser versions. It’s been available across browsers since January 2020.
The will-change CSS property enables optimizing animations by providing a rendering hint to the user agent about how an element is expected to change.
Syntax
/* Keyword values */
will-change: auto;
will-change: scroll-position;
will-change: contents;
/* <custom-ident> values */
will-change: transform;
will-change: opacity;
/* multiple values */
will-change: left, top;
/* Global values */
will-change: inherit;
will-change: initial;
will-change: revert;
will-change: revert-layer;
will-change: unset;
Values
The value is either auto or one or more comma separated <animateable-feature> values:
auto-
The default value. The browser applies whatever heuristics and optimizations it normally does.
<animateable-feature>-
Either
scroll-position,contents, or a<custom-ident>matching for the name of a built-in CSS property.scroll-position-
The scroll position of the element is expected to change in the near future, indicating the browser can optimize the rendering of overflowing content.
contents-
The element's contents, including all the elements in its subtree, are expected to change in the near future, indicating the browser can cache the element less aggressively.
<custom-ident>-
The name of a CSS property, as an
<ident>, whose value will be animated or otherwise change in the near future. If the<ident>given represents a property shorthand, all of its longhand components are applied. The value cannot bewill-change,none,allauto,scroll-position, orcontents.
Description
The will-change property provides a rendering hint to the browser indicating which properties are expected to be animated or otherwise changed. This enables browser to create the necessary rendering optimizations to enable smoother changes, and avoid jank.
The will-change property is aimed at improving rendering performance. This property can improve performance for elements with frequent repaints and reflows or complex visual effects like box-shadow and clip-path.
Applying the property to an element applies the value to the element's entire subtree, indicating any of the descendants can change. For this reason, applying a non-auto value on a large section, such at the <body>, can actually be bad for a page's performance. Instead,limit the use of this property to deeply nested elements, containing as little of the document as possible.
Warning:
The will-change property is intended to be used as a last resort, in order to try to deal with existing performance problems. It should not be used to anticipate performance problems.
Proper usage of this property can be a bit tricky:
- Don't apply will-change to too many elements. The browser already tries as hard as it can to optimize everything. Some of the stronger optimizations that are likely to be tied to
will-changeend up using a lot of a machine's resources, and when overused like this can cause the page to slow down or consume a lot of resources. - Use sparingly. The normal behavior for optimizations that the browser make is to remove the optimizations as soon as it can and revert back to normal. But adding
will-changedirectly in a stylesheet implies that the targeted elements are always a few moments away from changing and the browser will keep the optimizations for much longer time than it would have otherwise. So it is a good practice to switchwill-changeon and off using script code before and after the change occurs. - Don't apply will-change to elements to perform premature optimization. If your page is performing well, don't add the
will-changeproperty to elements just to wring out a little more speed.will-changeis intended to be used as something of a last resort, in order to try to deal with existing performance problems. It should not be used to anticipate performance problems. Excessive use ofwill-changewill result in excessive memory use and will cause more complex rendering to occur as the browser attempts to prepare for the possible change. This will lead to worse performance. - Give it sufficient time to work. This property is intended as a method for authors to let the user-agent know about properties that are likely to change ahead of time. Then the browser can choose to apply any ahead-of-time optimizations required for the property change before the property change actually happens. So it is important to give the browser some time to actually do the optimizations. Find some way to predict at least slightly ahead of time that something will change, and set
will-changethen. - Be aware, that will-change may actually influence the visual appearance of elements, when used with property values, that create a stacking context (e.g., will-change: opacity), as the stacking context is created up front.
Animations
If applying will-change to improve animations, add the property before the start of the animation. Animated properties behave as if included in a set will-change property value. For this reason, there is no reason to add the property within your @keyframes animation definitions.
Via stylesheet
It may be appropriate to include will-change in your style sheet for an application that does page flips on key presses like an album or a slide deck presentation where the pages are large and complex. This will let browser prepare the transition ahead of time and allow for snappy transitions between the pages as soon as the key is pressed. But use caution with the will-change property directly in stylesheets. It may cause the browser to keep the optimization in memory for much longer than it is needed.
.slide {
will-change: transform;
}
Formal definition
| Initial value | auto |
|---|---|
| Applies to | all elements |
| Inherited | no |
| Computed value | as specified |
| Animation type | discrete |
Formal syntax
will-change =
auto |
<animateable-feature>#
<animateable-feature> =
scroll-position |
contents |
<custom-ident>
Examples
Basic usage
This example demonstrates basic CSS application of the will-change property.
CSS
We use CSS to apply the will-change property to our #element, proving a hint to the browse that the transform and opacity property values will be animated or otherwise change in the near future.
#element {
willchange: transform, opacity;
}
Via script
This example shows how to apply the will-change property when needed and remove optimizations when done using JavaScript, which is generally how will-change should be applied.
JavaScript
We use JavaScript to add the will-change property to our #element when the element is hovered by using the mouseenter event. Setting will-change to transform, opacity tells the browser to optimize for changes to the transform and opacity properties. When the animationend event occurs, our script sets the value to auto.
const el = document.getElementById("element");
el.addEventListener("mouseenter", hintBrowser);
el.addEventListener("animationEnd", removeHint);
function hintBrowser() {
this.style.willChange = "transform, opacity";
}
function removeHint() {
this.style.willChange = "auto";
}
Specifications
| Specification |
|---|
| CSS Will Change Module Level 1 # will-change |