The compositor and the frame budget: which properties are free

Five stages, three exits

Every visual change walks some prefix of one pipeline, once per output frame: JS (event handlers, rAF callbacks, React render and commit) → style (recompute which rules apply and the computed values) → layout (geometry: where every box sits and how big it is — one width change cascades through siblings, ancestors, and line boxes) → paint (rasterize boxes into layer bitmaps: text, colors, shadows, borders) → composite (position the already-rasterized layers against each other and present the frame).

The expensive truth: properties differ not in how “heavy” they are but in where they enter the pipeline. Change width, top, margin, font-size — you dirty layout, and everything below re-runs: layout, paint, composite, on every frame of your animation. Change color, background, box-shadow — layout survives, but the element repaints. Change transform or opacity on an element with its own composited layer — nothing recomputes except the final placement of an existing bitmap: no layout, no paint. The compositor slides a texture. That is the entire reason “animate transform and opacity” is a rule and not a taste: they are the two commonly animated properties whose updates can skip the main thread entirely (plus filter in modern engines, with caveats).

The compositor thread is your only off-main-thread ally

Composite is not just the last stage — it lives on a different thread. The compositor thread holds the rasterized layers and can re-place them on screen without consulting the main thread. Declarative animations — CSS transitions, CSS animations, and Web Animations API calls — on transform and opacity are handed to it: after the handoff, the main thread can block for hundreds of milliseconds in reconcile or GC and the animation does not drop a frame, because its frame production happens entirely off the main thread. That is the Hook’s ending: the CSS-transition panel sailed through a 70 ms reconcile that had previously eaten four frames whole.

The flip side: any animation driven by JavaScript per frame — a rAF loop, a spring library mutating styles, React state — is main-thread by construction. It can still hit 60 fps, but it competes with everything else on that thread for every single frame and loses by default whenever React commits something big. And a CSS animation of a layout property is also main-thread work: the declarative form does not save you; the property class does.

Frame budget arithmetic

Numbers matter here because a single missed deadline drops a visible frame — not a slow one, a missing one. At 60 Hz a frame is 16.7 ms. At 120 Hz — increasingly the default on phones and laptops you do not test on — it is 8.3 ms. The budget is not all yours: the browser spends part of every frame on input processing, style recalculation, layout, paint, and the commit to the compositor. The residue for your JS is roughly 10 ms at 60 Hz and 3–5 ms at 120 Hz. Numbers worth carrying: style recalc on a few thousand nodes runs 1–4 ms; layout on a complex page 4–12 ms; a medium React commit 2–8 ms. Each is affordable once per interaction. None is affordable per frame at 120 Hz. Miss the deadline and the frame is not late — it is dropped: the previous frame stays on screen for an extra 16.7 (or 8.3) ms, and in continuous motion the eye reliably reads a single dropped frame as a hitch.

The React-specific sin: a render per frame

// ❌ a render per frame: rAF → setState → render → reconcile → commit, 60×/s
useEffect(() => {
  let raf;
  const tick = () => {
    setX((x) => x + dx);              // schedules a full React render each frame
    raf = requestAnimationFrame(tick);
  };
  raf = requestAnimationFrame(tick);
  return () => cancelAnimationFrame(raf);
}, []);

// ✅ React renders once; frames mutate the ref — no reconcile in the hot loop
useEffect(() => {
  let raf, x = 0;
  const tick = () => {
    x += dx;
    el.current.style.transform = `translateX(${x}px)`;
    raf = requestAnimationFrame(tick);
  };
  raf = requestAnimationFrame(tick);
  return () => cancelAnimationFrame(raf);
}, []);

The first loop pays React’s full machinery per frame: render the component, reconcile the subtree, commit — then style, layout, and paint if the written property demands them. A 3 ms commit is a third of the 8.3 ms budget before the browser does any rendering work. The second loop costs microseconds of JS and dirties only what the mutated property dirties — with transform on a promoted layer, nothing the main thread cares about.

The ladder, in order of preference: CSS transitions and animations first (declarative, compositor-eligible, interruption handled by the browser); WAAPI el.animate() when you need dynamic values or JS-controlled timing (still compositor-eligible); rAF + ref mutation when the value is genuinely computed per frame by JS — gestures, physics — main-thread but reconcile-free; setState per frame never. React’s job is the state at the boundaries: start the animation, commit the final value once when it ends.

will-change, honestly

will-change: transform asks the browser to promote the element to its own composited layer ahead of time, so the first animation frame does not pay promotion (which can itself trigger a paint). When you reach for it, ask yourself whether you actually need the first-frame saving or whether you are adding it defensively across the board. The cost is what the Hook’s folklore fix discovered: a layer is a bitmap, roughly width × height × 4 bytes × devicePixelRatio² — one full-screen layer at 2× DPR is on the order of 30 MB, and four hundred promoted table rows are four hundred rasterized textures the GPU must hold and composite every frame. More layers also mean slower raster and longer compositor frames, so blanket promotion makes the slow machines slower. The discipline: promote just-in-time — set will-change on press intent or right before animating, remove it when the animation ends — never in a stylesheet wildcard. And remember that browsers auto-promote elements with running transform or opacity animations anyway: will-change buys you the first frame, not the animation.

Reading the flames — and the INP connection

In the DevTools Performance panel, record the janky interaction and read three things. The Frames track: dropped and partially-presented frames show exactly when the budget broke. The Main flame chart: a purple Layout block recurring every 16 ms during your animation is the signature of animating a layout property; wide green Paint blocks mean a paint storm (an unpromoted animation, or a repaint-heavy property like box-shadow); long yellow JS tasks flagged with red triangles are your per-frame React work. The Rendering tab’s paint flashing and layer borders answer “what repaints” and “what got promoted” live, while you reproduce.

The INP connection makes this more than cosmetics: animation work and input handling share the main thread. A pointer event that arrives while your 24 ms animation frame is running waits for it; push interaction latency past 200 ms and INP is rated poor — the janky animation is now a Core Web Vitals regression. Compositor-driven animation is exempt by construction: it cannot block input it never shares a thread with.