will-change

will-change is a rendering hint about an expected future change. It does not trigger a transition, guarantee a GPU layer, or prove a performance improvement. Start without it and add it only for a measured problem.

Inspect the default instead of inventing a visual effect

The checkbox changes a transform with will-change:auto. The computed value is printed below. No special hint is necessary to make the transform work.

<input class="move" id="move" type="checkbox" /><label for="move"
  >Move the box</label
>
<div class="box" aria-hidden="true"></div>
<p>Computed will-change: <output id="hint"></output></p>
<script>
  document.getElementById("hint").textContent = getComputedStyle(document.querySelector(".box")).willChange;
</script>

.box {
  width: 80px;
  height: 60px;
  background: #2563eb;
  margin: 1rem;
  will-change: auto;
}
.move:checked ~ .box {
  transform: translateX(80px);
}

Separate preparation from the change

For a controlled performance experiment, Prepare sets the hint before the later movement. Clear removes it. Inspect the computed value or a performance recording; this demonstration does not claim the hint made movement faster.

<button type="button" id="prepare">Prepare hint</button
><button type="button" id="move">Toggle position</button
><button type="button" id="clear">Clear hint</button>
<div class="box" aria-hidden="true"></div>
<output aria-live="polite">Hint: auto</output>
<script>
  const box = document.querySelector(".box"); const output = document.querySelector("output"); document.getElementById("prepare").onclick = () => { box.style.willChange = "transform"; output.textContent = "Hint: " + getComputedStyle(box).willChange; }; document.getElementById("move").onclick = () => { box.style.transform = box.style.transform ? "" : "translateX(80px)"; }; document.getElementById("clear").onclick = () => { box.style.willChange = "auto"; output.textContent = "Hint: auto"; };
</script>

.box {
  width: 80px;
  height: 60px;
  background: #2563eb;
  margin: 1rem;
}
button {
  font: inherit;
  padding: 0.75rem;
  margin: 0.25rem;
}

Values and defaults

The initial value is auto and the property is not inherited. Auto leaves normal browser heuristics in place. Property names such as transform/opacity, and the distinct keywords scroll-position/contents, describe expected changes. Contents is not a CSS property name. A comma-separated list can supply multiple hints; all and none are not valid substitutes for auto.

Common mistakes

Persistent hints on many elements can consume resources and harm performance. Add a justified hint early enough to prepare, then remove it when it is no longer needed. Hints for stacking-context-creating properties can establish that context before the actual change, affecting z-index. Measure memory, rendering, and interaction on target devices; a computed hint is not evidence of a particular optimization.

Learn transform, opacity, and z-index.

Sources and browser support

MDN: will-change describes the syntax and links to the specification and compatibility data. Check individual values in that table when supporting older browsers.