completefrontend
Open lab My progress
THE WEB PERFORMANCE FIELD GUIDE

Compositor-friendly animation

Why a busy main thread freezes some animations and not others: what the compositor can animate alone, and when to use CSS, element.animate() or rAF.

By the end, you can
  • 01
    Pick properties the compositor can animateTell which properties skip layout and paint, and which make the main thread work in every frame.
  • 02
    Choose CSS, element.animate() or a loopKnow which ways of animating keep moving while the main thread is busy, and when a requestAnimationFrame loop is still right.
  • 03
    Find animations that aren't compositedRead the Performance panel's Animations and Frames tracks, and say why Chrome kept an animation on the main thread.

The leaf kept swaying, and the +1 froze

Asha is back on Leaf and Kettle's mint tea reviews. The small leaf next to the title still sways, as it did in lesson 31.4. And Ravi has finally added the "+1" he planned there. When someone taps Helpful, a green +1 appears next to the button. It rises 40 px in 800 ms, then goes away.

Asha taps Helpful on Meera's review. The +1 appears and starts to rise. Then it stops, and hangs in the air. Then it jumps most of the way up. The leaf never stopped swaying.

What happened? 150 ms after the tap, the server answered the vote. Then Ravi's code worked out the most helpful reviews again. That kept the page busy for 400 ms. Here is what Asha saw, in real frames from Chrome:

Asha's phone shows the Mint tea reviews page: the leaf at the top right, and Meera's review at the bottom with its Helpful button. Next to it, four real frames of the +1 beside the button, at 87 ms, 287 ms, 487 ms, 687 ms after Asha's tap: 1.6 px up, 6.6 px up, 6.6 px up, 31.3 px up. Under them, one bar for each frame Chrome drew, as tall as the +1 had risen. Ravi's ranking code ran from 151.5 ms for 400.5 ms. The bars in that time stay at the same height. Then they jump.Asha's screenAsha's phone before her tap: the Leaf and Kettle header, the title Mint tea reviews with a small green leaf at the right, and the reviews of Asha, Ravi and Meera. Meera's Helpful button is at the bottom.87 ms287 ms487 ms687 msThe +1: a requestAnimationFrame loop that sets topMeera's Helpful button and the +1 beside it, 87 ms after the tap, 1.6 px up.Meera's Helpful button and the +1 beside it, 287 ms after the tap, 6.6 px up.Meera's Helpful button and the +1 beside it, 487 ms after the tap, 6.6 px up.Meera's Helpful button and the +1 beside it, 687 ms after the tap, 31.3 px up.Every frame Chrome drew: how high the +1 wastap, 0 msRavi's ranking code, 400.5 ms800 ms
Real frames from Chrome, placed in time. Each thin bar is one frame Chrome drew, as tall as the +1 had risen. While Ravi's ranking code ran (shaded), Chrome kept drawing frames for the leaf, but the +1 stayed where it was. Then it jumped.

Here are the main numbers as code:

Asha's tap on HelpfulPop out in the code editor (opens in a new tab)JavaScript
// Asha taps Helpful. From Chrome's trace; times in ms after her tap.const ranking = { startsAt: 151.5, lastsMs: 400.5, framesDrawn: 23 };const plusOne = { risenAtStart: 4.9, risenAtEnd: 6.6 }; // px, of 40 console.log(`Ravi's ranking code ran for ${ranking.lastsMs} ms.`);console.log(`Chrome drew ${ranking.framesDrawn} frames during it.`);console.log(`The +1 rose ${(plusOne.risenAtEnd - plusOne.risenAtStart).toFixed(1)} px during it.`);
  • Line 1 is a comment. A trace is Chrome's detailed record of everything it did, as in lesson 7.2. A millisecond (ms) is a thousandth of a second.
  • Line 2 holds when Ravi's ranking code started, how long it ran, and how many frames Chrome drew meanwhile. A frame is one picture on the screen.
  • Line 3 holds how high the +1 was, in pixels, when that code started and when it ended.
  • Line 5 prints Ravi's ranking code ran for 400.5 ms. Line 6 prints Chrome drew 23 frames during it.
  • Line 7 prints The +1 rose 1.7 px during it.

So Chrome never stopped drawing. The leaf's sway still needed new frames, and the compositor drew them. But in those 23 frames, the +1 barely moved. Its 1.7 px came right at the start. When Ravi's code ended, the +1 jumped 19.8 px in one frame.

Why the difference? It's about who moves each one. You met two of Chrome's workers in lesson 6.1:

  • The main thread runs the page's JavaScript. It also works out styles, layout and paint. Ravi's ranking code ran there.
  • The compositor thread puts the finished layers together into frames. A layer is a part of the page Chrome draws on its own. The compositor can move a layer, or fade it, by itself.

The leaf's sway is a CSS animation of transform. Chrome gave the whole animation to the compositor thread when it started. Ravi's +1 is moved by a JavaScript loop. It sets top before every frame, so every frame needs the main thread.

Real-life analogyA traffic light and a traffic officer

At a busy crossing, a traffic light changes on its own timer. Nobody has to stand next to it. A traffic officer can wave the cars on just as well, but only while he's there. If he stops to take a phone call, every car waits until he's done.

In real life: The traffic light's own timer
In JavaScript: The compositor thread, running an animation it was given
In real life: Setting the timer once
In JavaScript: Starting a CSS animation or element.animate()
In real life: The officer waving each car on
In JavaScript: A loop that sets a new value before every frame
In real life: The officer's phone call
In JavaScript: A long task on the main thread
The main idea

An animation keeps moving while the main thread is busy only if the compositor can run it alone. Two things decide that. The property must be one the compositor can change, like transform or opacity. And the browser must drive the animation, through CSS or element.animate(), not a JavaScript loop.

This lesson tries each half on its own: first the property, then the way of animating. For the basics of CSS and JavaScript animation, see Animation with JavaScript.

How the course recorded it

  • The browser: Chrome 157, on a screen the size of Asha's phone: 412 by 823 px. Its CPU was slowed 4 times, as in lessons 31.1 to 31.4. That slows the page's main thread only. The compositor thread ran at the computer's full speed.
  • The page: Ravi's page from lesson 31.4, with 1,000 reviews and the swaying leaf. The +1 sits on top, with z-index: 1, as that lesson advised for anything that moves.
  • The versions: 17 versions of the +1. Four ways to animate it, times four properties, and Ravi's last version.
  • Calm and busy: each version on a calm page, and on a busy one. On the busy page, a 150 ms wait stands in for the server's answer. A loop that keeps the main thread busy for 400 ms stands in for the ranking code.
  • The taps: real mouse clicks on Meera's Helpful button. The course tapped each calm page 9 times and each busy page 5 times, and kept the middle tap.
  • The frames: Chrome's own screenshots in the trace show where the +1 was in each frame. The times come from the course's computer, so yours will differ.

Which properties can skip layout and paint

Lesson 6.3 showed the steps Chrome takes to draw a change:

  • Recalculate style works out each element's final styles.
  • Layout works out the size and place of every box.
  • Paint writes the drawing commands.
  • Composite puts the layers together into a frame. This step runs on the compositor thread.

A change starts at the first step it affects, and runs every step after it. An animation is a change in every frame. So the property you animate decides how much work each frame needs.

The course gave the +1 one CSS transition, with four properties in turn. top and transform make it rise. color and opacity make it fade. These taps were on the calm page:

One transition, four propertiesPop out in the code editor (opens in a new tab)JavaScript
// The +1 as a CSS transition of each property. Middle of 9 calm taps.const taps = [  { property: "top", mainMs: 565.5, layouts: 56, paints: 50 },  { property: "color", mainMs: 231.7, layouts: 2, paints: 50 },  { property: "transform", mainMs: 51.8, layouts: 2, paints: 2 },  { property: "opacity", mainMs: 44.8, layouts: 2, paints: 2 },];for (const t of taps) {  console.log(`${t.property}: ${t.mainMs} ms, Layout ${t.layouts}x, Paint ${t.paints}x`);}
  • Lines 3 to 6 hold the middle tap for each property. mainMs is the main thread's working time in the 850 ms after the tap. The other two count how many times Layout and Paint ran.
  • Line 9 prints top: 565.5 ms, Layout 56x, Paint 50x and color: 231.7 ms, Layout 2x, Paint 50x.
  • Then transform: 51.8 ms, Layout 2x, Paint 2x and opacity: 44.8 ms, Layout 2x, Paint 2x.
The +1 as a CSS transition of four properties, one calm tap each. top: Style and Layout and Paint in most frames, 565.5 ms of main-thread time. color: Style and Paint in most frames, 231.7 ms of main-thread time. transform: no main-thread step in most frames, 51.8 ms of main-thread time. opacity: no main-thread step in most frames, 44.8 ms of main-thread time. The compositor drew every frame in all four.main thread, frame by framecompositormain-thread timetopStyleLayoutPaintComposite565.5 mscolorStyleLayoutPaintComposite231.7 mstransformStyleLayoutPaintComposite51.8 msopacityStyleLayoutPaintComposite44.8 ms
Plain cards ran in almost every frame. Crossed-out cards ran only when the +1 started and ended. The compositor, shaded, drew every frame for all four.

Chrome drew about 51 frames for each tap. So with top, Layout ran in nearly every frame. top moves the +1 inside the page's layout. Every frame needed style, layout and paint: 565.5 ms of work in 850 ms.

color skipped layout, because the +1 stays where it is. But a new color must be painted, so Paint ran in almost every frame.

transform and opacity ran Layout and Paint twice: when the +1 appeared, and when it went away. In between, the main thread did nothing for it. The compositor moved it, or faded it, by itself.

Real-life analogyThe specials board on a rail

The café's specials board hangs on a rail. To move it along, you slide it. Nothing else changes. To dim it, you turn down the lamp above it. But to hang it on another wall, the shelf under it has to move too. And to change its colour, someone has to write it all again.

In real life: Sliding the board along its rail
In JavaScript: transform: the compositor moves the layer
In real life: Turning down the lamp above it
In JavaScript: opacity: the compositor fades the layer
In real life: Moving it to another wall, shelf and all
In JavaScript: top: layout and paint run again
In real life: Rewriting it in a new colour of chalk
In JavaScript: color: paint runs again

Chrome's list of compositor properties

Which properties can Chrome's compositor animate? Its source keeps a list, on lines 78 to 84 of compositor_animations.cc:

  • transform, and its parts translate, rotate and scale;
  • opacity;
  • filter and backdrop-filter, from lesson 31.4;
  • background-color and clip-path, which Chrome can animate with built-in painters that work away from the main thread.

Even on the list, some values stay on the main thread. A filter that moves pixels, like blur(), does (lines 404 to 416). Any property off the list, like top, width or box-shadow, is an "unsupported CSS property" to the compositor.

The last item is Chrome's own. web.dev's advice is the safe one for every browser: "Modern browsers can animate two CSS properties cheaply: transform and opacity." Why it matters: to move something, animate transform. To fade it, animate opacity. Then each frame costs the main thread nothing. Pick a property to see what its transition cost:

Playground: one CSS transition, four properties
The +1's transitionCSS
.plus { top: -36px; transition: top 800ms linear; }
@starting-style { .plus { top: 4px; } }
topRecorded
Main-thread time565.5 ms
Recalculate style58 times
Layout56 times
Paint50 times
Frames Chrome drew51
Run by the compositorno
Try it yourself
top: 565.5 ms of main-thread time

top moves the +1 in the layout. Chrome restyled it, laid the page out and painted it again in almost every frame.

Recorded in Chrome 157 with the main thread 4 times slower. Each number is the middle of 9 calm taps, over the 850 ms after the tap.

CSS transitions and animations

A CSS transition moves a property from its old value to its new one, whenever the value changes. Here is the +1's transition, with transform:

The +1 as a CSS transitionCSS
.plus { transform: translateY(-40px); transition: transform 800ms linear; }
@starting-style { .plus { transform: translateY(0); } }
  • Line 1 gives the +1 its end place, 40 px up. transition says: when transform changes, take 800 ms, at a steady speed (linear).
  • Line 2 gives the +1 a value to start from. A new element has no old value. The CSS Transitions spec starts no transition for an element that wasn't in the page at the last style change. @starting-style gives it an old value: in place, 0 px up.

Ravi's JavaScript only adds the +1, and takes it away at the end:

Starting the transitionJavaScript
function plusOne(button) {
  const plus = makePlus(button);
  plus.addEventListener("transitionend", () => plus.remove());
}

Line 2 makes the +1, a span with the text "+1", and puts it inside the button. Line 3 removes it when the transition ends.

A CSS animation plays keyframes: a list of values at points in time. It starts when the element gets it, so it needs no old value:

The +1 as a CSS animationCSS
.plus { animation: plus-one 800ms linear forwards; }
@keyframes plus-one { from { transform: translateY(0); } to { transform: translateY(-40px); } }
  • Line 1 plays the keyframes named plus-one once, over 800 ms. forwards keeps the last value after the end, until Ravi's code removes the +1.
  • Line 2 holds the keyframes: from the start, to 40 px up.

Inside the browser, both are the same kind of object. The CSS specs make a transition a CSSTransition and an animation a CSSAnimation. Both are a kind of Animation, the object the next section is about.

The busy page

Now the course ran the same versions with Ravi's ranking code:

Four CSS versions on the busy pagePop out in the code editor (opens in a new tab)JavaScript
// Ravi's ranking code keeps the main thread busy for 400 ms.// How far did each +1 rise meanwhile? Middle of 5 busy taps.const plusOnes = [  { css: "a transition of top", risenPx: 3.3 },  { css: "a transition of transform", risenPx: 19.8 },  { css: "an animation of top", risenPx: 1.7 },  { css: "an animation of transform", risenPx: 19.8 },];for (const p of plusOnes) console.log(`${p.css}: ${p.risenPx} px`);
  • Lines 4 to 7 hold how far each +1 rose while the ranking code ran.
  • Line 9 prints a transition of top: 3.3 px and a transition of transform: 19.8 px.
  • Then an animation of top: 1.7 px and an animation of transform: 19.8 px.

In 400 ms, an 800 ms rise of 40 px should cover 20 px. The transform versions rose 19.8 px. The top versions rose 3.3 and 1.7 px, all at the very start. That was their last change from before the ranking code began, which reached the screen just after. Then they waited.

Why it matters: CSS alone doesn't keep an animation moving. A CSS animation of top froze just like Ravi's loop. It's the property that lets the compositor take over.

Chrome writes down why

When an animation starts, Chrome checks whether the compositor can run it. It writes the answer into the trace, as a number called compositeFailed. For the transition of top, the number was 8224. For transform, there was no failure.

8224 is two reasons added together. Chrome's source gives each reason its own number:

  • 8192, "Unsupported CSS property": the compositor can't animate top at all. The trace names the property too.
  • 32, "Target has invalid compositing state": the +1 had nothing the compositor could change. Chrome keeps each element's transform and opacity in its property trees, from lesson 31.4. A compositor animation changes one entry there. The top +1 had no entry of its own.
Real-life analogyA parcel sent back with labels

Ravi gives a parcel to a courier. The courier hands it back with two labels: "We don't carry this kind of item" and "No address on the box". Either label alone would be enough. So Ravi has to deliver it himself, on foot, between serving customers.

In real life: The parcel
In JavaScript: The +1's animation
In real life: The courier who delivers on his own
In JavaScript: The compositor thread
In real life: "We don't carry this kind of item"
In JavaScript: Unsupported CSS property: top
In real life: "No address on the box"
In JavaScript: Target has invalid compositing state
In real life: Ravi delivering it himself
In JavaScript: The main thread running every frame

The Web Animations API: element.animate()

The Web Animations API lets JavaScript make the same animations as CSS. element.animate() takes keyframes and a timing, and starts at once:

The +1 with element.animate()JavaScript
function plusOne(button) {  const plus = makePlus(button);  const rise = plus.animate([{ transform: "translateY(0)" }, { transform: "translateY(-40px)" }], { duration: 800, easing: "linear", fill: "forwards" });  rise.finished.then(() => plus.remove());}
  • Line 3 holds two keyframes: from 0 px up to 40 px up. Then the timing: 800 ms, at a steady speed. fill: "forwards" keeps the last value at the end.
  • Line 3 also keeps what animate() returns: an Animation object, here called rise.
  • Line 4 waits for rise.finished, a promise that resolves when the animation ends. Then it removes the +1.

The Web Animations spec says what animate() makes. A keyframe effect holds the keyframes, the timing and the element. An Animation plays that effect on a timeline, a clock it reads its time from. Each page has one, document.timeline, which starts at zero when the page does.

Does starting it from JavaScript make it a JavaScript animation? No. The spec says the API makes animations "that have the same behavior and performance characteristics as declarative animations", the ones written in CSS. The recording agrees. On the busy page, the transform +1 rose 19.8 px during the ranking code, and the top one rose 3.3 px. That's the same as CSS.

Real-life analogyThe café's TV and its remote

The café plays a tea-making video on its TV. Once it's playing, the TV plays it by itself, even while Ravi serves. But Ravi keeps the remote. He can pause the video, rewind it or play it faster. And the end screen tells him it's over.

In real life: The TV playing the video by itself
In JavaScript: The compositor running the animation
In real life: The remote in Ravi's hand
In JavaScript: The Animation object animate() returns
In real life: Pause, rewind, play faster
In JavaScript: pause(), reverse(), playbackRate
In real life: The end screen
In JavaScript: The finished promise

animate() hands you that remote straight away. A CSS animation has one too, but you have to find it first, with getAnimations(). With it, Ravi's code can pause the animation, play it backwards with reverse(), change its speed, or wait for finished. Why it matters: when your code needs that control, use element.animate(), not a loop. You keep the compositor.

Keeping the end value: commitStyles()

The +1 goes away at the end, so fill: "forwards" is enough there. But say Ravi's Helpful button should grow a little after a vote, and stay bigger. The spec warns: "Authors are discouraged from using fill modes to produce animations whose effect is applied indefinitely." Instead, write the end value into the element's own style, then remove the animation:

Grow, then keep the sizePop out in the code editor (opens in a new tab)JavaScript
const button = document.querySelector(".helpful");const grow = button.animate([{ scale: 1 }, { scale: 1.1 }], { duration: 200, fill: "forwards" });grow.finished.then(() => {  grow.commitStyles();  grow.cancel();  console.log(button.style.scale);  console.log(button.getAnimations().length);});
  • Line 2 grows the button from scale 1 to 1.1 in 200 ms. scale is one of the compositor's properties.
  • Lines 3 to 5 run when it finishes. commitStyles() writes the end value into the button's style attribute. cancel() removes the animation.
  • Line 6 prints 1.1: the size now lives in the button's own style. Line 7 prints 0: no animation is left.

Ravi's last +1

Ravi's last version rises and fades at the same time, in one call:

Ravi's last +1JavaScript
function plusOne(button) {  const plus = makePlus(button);  const rise = plus.animate(    [      { transform: "translateY(0)", opacity: 1 },      { transform: "translateY(-40px)", opacity: 0 },    ],    { duration: 800, easing: "linear", fill: "forwards" },  );  rise.finished.then(() => plus.remove());}
  • Line 5 is the first keyframe: in place, fully visible. Line 6 is the last: 40 px up, with opacity 0.
  • Line 8 is the timing, as before. Line 10 removes the +1 when it finishes.

On the busy page, it rose 18.2 px while the ranking code ran. Chrome drew 24 frames in that time, and none of them was late. Here it is next to his first +1, in real frames:

Real frames of the +1 beside Meera's Helpful button, at four moments after Asha's tap. Ravi's first +1, a requestAnimationFrame loop that sets top, is at the same height at 287 ms and 487 ms. Ravi's last +1, made with element.animate() of transform and opacity, is higher and paler in every frame, while his ranking code ran from 151.2 ms for 400.6 ms.89 ms289 ms489 ms689 msRavi's first +1: a loop that sets topRavi's first +1, 87 ms after the tap, 1.6 px up.Ravi's first +1, 287 ms after the tap, 6.6 px up.Ravi's first +1, 487 ms after the tap, 6.6 px up.Ravi's first +1, 687 ms after the tap, 31.3 px up.Ravi's last +1: element.animate(), transform and opacityRavi's last +1, 89 ms after the tap, 1.6 px up and fading.Ravi's last +1, 289 ms after the tap, 11.5 px up and fading.Ravi's last +1, 489 ms after the tap, 21.4 px up and fading.Ravi's last +1, 689 ms after the tap, 29.7 px up and fading.tap, 0 msRavi's ranking code, 400.6 ms800 ms
The same tap, the same ranking code. Ravi's last +1 rose and faded in every frame while the code ran (shaded), because the compositor moved it.

requestAnimationFrame loops

Ravi's first +1 used neither CSS nor element.animate(). It's a requestAnimationFrame loop: a function that sets a new value just before each frame. Lesson 6.2 showed how requestAnimationFrame() works. Here is Ravi's code:

Ravi's first +1JavaScript
function plusOne(button) {  const plus = makePlus(button);  let start;  requestAnimationFrame(function step(now) {    start ??= now;    const t = Math.min((now - start) / 800, 1);    plus.style.top = `${4 - 40 * t}px`;    if (t < 1) requestAnimationFrame(step);    else plus.remove();  });}
  • Line 4 asks the browser to call step before the next frame. now is that frame's time, in ms.
  • Line 5 keeps the first frame's time as the start.
  • Line 6 works out how far through the 800 ms it is: 0 at the start, 1 at the end.
  • Line 7 sets top: from 4 px at the start to -36 px at the end, 40 px higher.
  • Line 8 asks for the next frame until the end. Then line 9 removes the +1.

The HTML spec runs these callbacks as part of each frame, just before the browser recalculates styles and lays out the page. They run on the main thread. So while the ranking code holds the main thread, no callback runs, and nothing sets a new value.

Real-life analogyA stop-motion film

In a stop-motion film, an animator moves a clay figure a little, then takes one photo. Then another little move, another photo. The film only moves while she keeps working. If she goes to answer the door, the film stops. When she comes back, she moves the figure to where it should be by now.

In real life: The animator
In JavaScript: The main thread, running the callback
In real life: Moving the clay figure a little before each photo
In JavaScript: Setting top or transform before each frame
In real life: Answering the door
In JavaScript: Ravi's ranking code, a long task
In real life: Moving the figure to where it should be by now
In JavaScript: Working out progress from the frame's time

What if Ravi only changed the property? The course tried the same loop with transform:

// The +1 in a requestAnimationFrame loop, two ways.// mainMs: calm taps. risenPx: while the ranking ran.const loops = [  { property: "top", mainMs: 603.4, risenPx: 1.7 },  { property: "transform", mainMs: 324.1, risenPx: 1.7 },];for (const l of loops) {  console.log(`${l.property}: ${l.mainMs} ms of main thread, rose ${l.risenPx} px`);}
  • Line 4 is the loop that sets top. Line 5 is the loop that sets transform.
  • Line 8 prints top: 603.4 ms of main thread, rose 1.7 px.
  • Then transform: 324.1 ms of main thread, rose 1.7 px.

transform skipped Layout and Paint, so a calm tap cost the main thread about half as much. But every frame still came from the main thread. Each one ran the callback, then Recalculate style, Pre-paint, Layerize and Commit. Pre-paint alone took 198.7 ms, updating the transform in Chrome's property trees.

And during the ranking code, the transform +1 froze just like the top one. Here are all four ways to move it, frame by frame:

How far the +1 had risen in each frame Chrome drew, after Asha's tap, while Ravi's ranking code ran from about 150.2 ms for about 400 ms. A CSS transition of transform: it rose 19.8 px while the code ran. A CSS animation of transform: it rose 19.8 px while the code ran. element.animate() with transform: it rose 19.8 px while the code ran. A requestAnimationFrame loop that sets transform: it rose 1.7 px while the code ran.Ravi's ranking codeA CSS transition of transformA CSS animation of transformelement.animate() with transformA requestAnimationFrame loop that sets transformtap, 0 ms850 ms
Each thin bar is one frame Chrome drew, as tall as the +1 had risen by then. The shaded band is the time Ravi's ranking code ran. Only the loop's +1 stopped, then jumped.

Line 6 of Ravi's loop is why his +1 jumped instead of falling behind. It works out the progress from the frame's time, not by counting frames. MDN warns that a loop should always use that time, "otherwise, the animation will run faster on high refresh-rate screens."

So when is a loop the right tool? When only JavaScript can work out each frame's value. A card that follows Asha's finger is one example. Drawing on a canvas is another. Then keep each callback short, and change only transform or opacity, so the frames skip layout and paint. Why it matters: a loop is never free. It needs the main thread for every frame.

Compare every way and every property the course recorded:

Playground: four ways to move the +1
The transform versionJavaScript
function plusOne(button) {
  const plus = makePlus(button);
  let start;
  requestAnimationFrame(function step(now) {
    start ??= now;
    const t = Math.min((now - start) / 800, 1);
    plus.style.transform = `translateY(${-40 * t}px)`;
    if (t < 1) requestAnimationFrame(step);
    else plus.remove();
  });
}
requestAnimationFrame loopRecorded
top: during the rankingrose 1.7 px
top: calm tap, main thread603.4 ms
transform: during the rankingrose 1.7 px
transform: calm tap, main thread324.1 ms
color: during the rankingfaded 6% more
color: calm tap, main thread222.4 ms
opacity: during the rankingfaded 4% more
opacity: calm tap, main thread133.1 ms
Try it yourself
requestAnimationFrame loop

Every property waited for the ranking code, even transform and opacity, because each new value comes from the main thread.

Recorded in Chrome 157 with the main thread 4 times slower. "During the ranking" is the middle of 5 busy taps; "calm tap" is the middle of 9 taps without the ranking code. The code shown is the transform version.

Finding animations that aren't composited

How could Ravi have found this himself? An animation the compositor runs is called composited. DevTools shows which animations aren't, and what that costs.

Record in the Performance panel while you tap. Its Animations track lists the page's animations. Chrome's docs say: "Non-compositing animations are marked with red triangles in the top right corner." Select one, and the Summary tab lists the reasons under Compositing failed. For the top transition, DevTools reads the two bits from the trace. It shows "Target has invalid compositing state" and "Unsupported CSS property: top".

A requestAnimationFrame loop isn't an animation to the browser, so it isn't listed. Ravi's first trace had no Animation events for the +1. Look for its cost elsewhere: the Main track shows Animation frame fired in every frame.

The Frames track shows when frames came late. While the ranking code ran on Ravi's first page, Chrome marked 23 frames as partly late. DevTools draws them as partially presented frames. In the docs' words, the main thread's work "is late but the compositor thread ... is in time." That's the leaf's sway arriving, and the +1 waiting. On Ravi's last page, there were none. Why it matters: after you add an animation, record it once, and look for red triangles and partly late frames.

The table adds two more tools. Read it across: your question, the tool, and what it shows.

Which tool answers which question
Your questionThe toolWhat it shows
Which animations aren't composited, and why?The Performance panel's Animations track, then the Summary tab.Each animation, a red triangle on the ones that aren't composited, and the reasons.
Did frames come late?The Performance panel's Frames track.Partially presented frames, where the main thread's part was late.
What runs on the main thread each frame?The Performance panel's Main track.Animation frame fired, then style, layout and paint, for a loop.
Which animations are running, and can I slow them down?The Animations panel, in the drawer.CSS transitions, CSS animations and element.animate(), which it can replay slowly.
Does a page have any at all?Lighthouse's Avoid non-composited animations audit.Each animated element that isn't composited, with the reasons you can fix.

The Lighthouse audit says: "Animations which are not composited can be janky and increase CLS." Janky means not smooth. Lesson 30.2 showed why a top animation can count as a layout shift. The audit lists only reasons you can act on, like an unsupported property.

Now try Ravi's code in your own browser. Pick a version, tap Helpful in the page below, and watch the +1 and the leaf:

Playground: the +1 in your browser
This version's +1JavaScript
function plusOne(button) {
  const plus = makePlus(button);
  let start;
  requestAnimationFrame(function step(now) {
    start ??= now;
    const t = Math.min((now - start) / 800, 1);
    plus.style.top = `${4 - 40 * t}px`;
    if (t < 1) requestAnimationFrame(step);
    else plus.remove();
  });
}
Loop + topLive
Try it yourself
Tap Helpful, and watch the +1 while the ranking code runs

This +1 needs the main thread in every frame, so it stops while the code runs, then jumps.

The page below is Meera's review with Ravi's real code, running in this browser. The ranking code keeps this whole tab busy for 400 ms, so the lesson page freezes too. A wider screen or a faster computer doesn't change what stops.

Will it keep moving?

Here are animations like Ravi's. For each one, ask two questions. Is the property one the compositor can change? And does the browser drive it, or a loop?

Will it keep moving?
  • A CSS transition of transform
  • element.animate() fading opacity
  • A CSS animation of rotate
  • A CSS animation of top
  • A CSS transition of color
  • A requestAnimationFrame loop that sets transform
  • A CSS animation of filter: blur()
  • element.animate() growing width
Try it yourself
0 of 8 correct

Sort each animation by what happens while the main thread is busy for 400 ms.

Choose a category for every card. You can change an answer at any time; Reset clears them all.

Then pick the tool. Read the table across: what you need, what to use, and why.

Picking a way to animate
If you needUseWhy
A move or fade when a class or style changes.A CSS transition.The browser drives it, and the compositor can run it.
A move with several steps, or one that repeats.A CSS animation.Keyframes describe every step, and it needs no old value.
To start, pause, reverse or wait for it from code.element.animate().It returns an Animation you can control, and it runs like CSS.
A value only JavaScript can work out in each frame.A requestAnimationFrame loop.Nothing else can, but it needs the main thread every frame.

Common mix-ups

  • "transform is always smooth." No. In a requestAnimationFrame loop, the transform +1 froze with the main thread, just like the top one.
  • "An animation started from JavaScript runs on the main thread." No. Chrome ran the element.animate() transform +1 on the compositor, just like CSS.
  • "CSS animations never need the main thread." No. A CSS transition of top ran Layout 56 times in 850 ms, all on the main thread.
  • "Fading with color costs the same as opacity." No. The color fade needed Paint in almost every frame: 231.7 ms of main-thread time, against 44.8 ms.
  • "If Chrome keeps drawing frames, the animation is smooth." No. Chrome drew 23 frames during the ranking code, all partly late. They had the leaf's sway, but not the +1's new place.
  • "fill: forwards is how you keep an animation's end value." No. The spec discourages filling forever. Use commitStyles(), then cancel().

Practice exercises

Answer first, then use the hints.

Exercise 1 · Warm-upFrames in 800 ms

How many frames does the +1's 800 ms take? What does the second line print?

Starter codePop out in the code editor (opens in a new tab)JavaScript
const durationMs = 800;
for (const hz of [60, 120]) {
  const frameMs = 1000 / hz;
  console.log(`${hz} Hz: ${Math.round(durationMs / frameMs)} frames`);
}

Answer, then press Check. Spacing and letter case don’t matter.

    Exercise 2 · Warm-upWhich one can the compositor run?

    Which line's transition can Chrome run on the compositor?

    Starter codeCSS
    .a { transition: left 300ms; }
    .b { transition: height 300ms; }
    .c { transition: scale 300ms; }
    .d { transition: box-shadow 300ms; }

    Answer, then press Check. Spacing and letter case don’t matter.

      Exercise 3 · PracticeA loop that fades

      In the four-ways playground, how long did the main thread work for the opacity +1 in a loop, on a calm tap?

      Answer, then press Check. Spacing and letter case don’t matter.

        Exercise 4 · PracticeA loop that counts frames

        This loop moves the +1 a fixed step in every frame. What does the second line print? Then fix the loop.

        Starter codePop out in the code editor (opens in a new tab)JavaScript
        // A loop that moves the +1 the same step in every frame.
        const stepPx = 40 / 48; // 48 frames in 800 ms on a 60 Hz screen
        for (const hz of [60, 120]) {
          const frames = Math.round(800 / (1000 / hz));
          console.log(`${hz} Hz: risen ${Math.round(frames * stepPx)} px after 800 ms`);
        }

        Answer, then press Check. Spacing and letter case don’t matter.

          Exercise 5 · ChallengeWhy the color fade isn't composited

          Open the course's copy of the color fade. What does DevTools give as the reason, with the property's name?

          Answer, then press Check. Spacing and letter case don’t matter.

            Exercise 6 · ChallengeChanging speed without a jump

            Ravi wants to slow his +1 down while it runs. Which Animation method does the spec say to use, so it doesn't jump?

            Answer, then press Check. Spacing and letter case don’t matter.

              Check your understanding

              For each question, ask: which property, and who drives it?

              The compositor animation quiz · 7 questionsScore: first tries count
              1. Question 1 of 7What does the last line of Asha's tap example print?

                Read the code, then predictPop out in the code editor (opens in a new tab)JavaScript
                // Asha taps Helpful. From Chrome's trace; times in ms after her tap.
                const ranking = { startsAt: 151.5, lastsMs: 400.5, framesDrawn: 23 };
                const plusOne = { risenAtStart: 4.9, risenAtEnd: 6.6 }; // px, of 40
                
                console.log(`Ravi's ranking code ran for ${ranking.lastsMs} ms.`);
                console.log(`Chrome drew ${ranking.framesDrawn} frames during it.`);
                console.log(`The +1 rose ${(plusOne.risenAtEnd - plusOne.risenAtStart).toFixed(1)} px during it.`);

                Choose an answer to see the explanation.

              2. Question 2 of 7While Ravi's ranking code ran, why did the leaf keep swaying?

                Choose an answer to see the explanation.

              3. Question 3 of 7Ravi moves the +1 with transform, but from a requestAnimationFrame loop. What happens during a 400 ms long task?

                Choose an answer to see the explanation.

              4. Question 4 of 7What does the second line of the four-properties example print?

                Read the code, then predictPop out in the code editor (opens in a new tab)JavaScript
                // The +1 as a CSS transition of each property. Middle of 9 calm taps.
                const taps = [
                  { property: "top", mainMs: 565.5, layouts: 56, paints: 50 },
                  { property: "color", mainMs: 231.7, layouts: 2, paints: 50 },
                  { property: "transform", mainMs: 51.8, layouts: 2, paints: 2 },
                  { property: "opacity", mainMs: 44.8, layouts: 2, paints: 2 },
                ];
                for (const t of taps) {
                  console.log(`${t.property}: ${t.mainMs} ms, Layout ${t.layouts}x, Paint ${t.paints}x`);
                }

                Choose an answer to see the explanation.

              5. Question 5 of 7In the Performance panel's Frames track, what does a partially presented frame mean?

                Choose an answer to see the explanation.

              6. Question 6 of 7Is element.animate() slower than a CSS animation, because it's JavaScript?

                Choose an answer to see the explanation.

              7. Question 7 of 7Ravi's button grows with element.animate() and should stay bigger. What should his code do once the animation has finished?

                Choose an answer to see the explanation.

              Key takeaways

              • An animation keeps moving while the main thread is busy only if the compositor runs it alone.
              • The compositor can animate transform and opacity. top needs layout in every frame, and color needs paint.
              • CSS transitions, CSS animations and element.animate() all make Animation objects. Chrome runs them on the compositor when the property allows.
              • A requestAnimationFrame loop needs the main thread for every frame, even with transform. Use one only when JavaScript must work out each value.
              • element.animate() gives you a handle: finished, pause(), reverse(), and commitStyles() to keep an end value.
              • DevTools shows non-composited animations, with Chrome's reasons, in the Animations track, and late frames in the Frames track.

              Remember the one-liner.
              Animate transform and opacity, and let the browser drive: the compositor keeps them moving while the main thread works.

              Sources

              The facts on this page come from these specs, docs and source files:

              Coming next: Scrolling performance. Asha scrolls Ravi's page, and the same two threads decide whether it follows her finger.

              CompleteFrontend Clear concepts. Working examples.