Chromium Compositor Behaviour for Scroll Timelines

Chromium has the most detailed compositing tooling of the three engines, which makes it the place to do the work — and also the place where it is easiest to reach conclusions that do not generalise. This guide covers what Chromium’s Layers panel is actually telling you about a scroll-driven page: why one intentional promotion often produces four layers, what raster tiling does and does not bound, and which compositing reasons are worth acting on. It sits under the engine support matrix.

When to use this approach

Reach for Chromium’s compositing tools when the symptom is about smoothness or memory rather than about correctness:

  • The animation stutters while the page stays responsive. Main-thread work would make the page unresponsive too; a responsive page with a stuttering animation points at the compositor.
  • A media-heavy section flashes blank areas. That is texture eviction, which means the layer budget has been exceeded.
  • The page feels heavier than the effect count suggests. Almost always overlap promotion, which produces layers nobody wrote a rule for.
  • Before adding an effect to a page that already has several. Establishing the current layer count is the only way to know whether there is room.

Use a different tool when the animation does not run at all, when it attaches to the wrong scroller, or when the timeline resolves to nothing — those are attachment questions and the compositor has nothing to say about them.

Reading compositing reasons Five compositing reasons and what each one means. An animated transform is the reason you want. A will-change hint is a reason you asked for. Overlap and a 3D transform are reasons the page produced incidentally, and a fixed position layer is one the layout produced. Only the first is guaranteed to be earning its memory. what the Layers panel says, and what it means has an animated transform intentional — the animation asked for it has a will-change hint deliberate — check it is still needed overlaps a composited layer incidental — the expensive surprise has a 3D transform often a leftover translateZ(0) hack Overlap promotion is the one worth hunting: one promoted element can promote everything painted above it.

Implementation

1. Open the Layers panel on the busiest section

The panel lists every composited layer with its dimensions, its estimated memory, and the reason it was promoted. Sort by memory and the top entries are usually where the whole budget went.

2. Read the reasons rather than the count

A layer count on its own is not actionable. The reasons split them into three groups: promotions your animation asked for, promotions a will-change hint asked for, and promotions the page produced incidentally.

3. Hunt the incidental promotions

Overlap promotion cascades One card is promoted because it animates. Three elements painted above it in the stacking order must also be promoted so the compositor can keep the paint order correct. One intentional layer becomes four, and the three extra ones are invisible in the stylesheet. animating card 1 intentional layer tooltip above it sticky header floating action button 3 promoted only because they paint above the animating one total: 4 layers for 1 animation stacking order, bottom to top

Overlap promotion is the largest source of unexpected layers. When an element is composited, anything painted above it in stacking order must also be composited so that paint order is preserved. A single animating card underneath a sticky header, a tooltip layer and a floating button turns one promotion into four.

The fix is usually structural rather than a property change: keep animating elements out from under persistent overlays, or give the overlays their own stacking context so the cascade stops.

4. Audit will-change hints 

/* the hint held for the whole session — a standing allocation */
.card { will-change: transform; }

/* scoped to the interaction that needs it */
.card:hover,
.card:focus-within { will-change: transform; }

An element with a running transform animation is promoted anyway, so a hint on it adds nothing but makes the promotion permanent.

5. Understand what tiling does bound

Tiling large layers A layer larger than the viewport is rasterised as tiles rather than as one texture. Tiles near the visible area are kept, and distant ones are discarded and re-rasterised when needed. This bounds the memory a single large layer can hold, and it is why a very tall promoted element does not cost its full area. a tall promoted layer visible — kept near — kept distant — discarded Tiling bounds what one layer can hold, so a very tall element does not cost its full painted area. It does not bound the layer COUNT, which is what most pages exceed. Many small layers cost more than one large one.

Verification

Record a scroll through the section with the Performance panel and confirm the frames track are clean and the paint track is empty. A page that is genuinely compositor-driven shows nothing in either scripting or paint during a scroll.

Then re-open the Layers panel with device emulation set to a mobile viewport and a device pixel ratio of three. The layer count usually stays the same and the memory figure multiplies by roughly nine, which is the number that matters and the one that desktop testing never shows.

Finally, use the rendering flags — layer borders and paint flashing — as a sanity check. Paint flashing highlighting a region on every scroll frame is unambiguous evidence that something is repainting, and it takes seconds where reading a trace takes minutes.

Edge cases and gotchas

translateZ(0) left over from an older codebase. It forces promotion for no current reason and is invisible in a search for will-change. Every one of them is a standing layer.

Layer memory reported per layer, not per page. The panel’s figures are individual; the total is what matters and has to be added up. Sorting by memory and summing the top ten is usually enough to know whether the page is in trouble.

Emulated device pixel ratio changes the memory figures but not the layer tree. Both matter, and they change independently — a structural fix reduces the count, a sizing fix reduces the memory per layer.

Promotions from position: fixed and backdrop-filter. Both are common in site chrome and both produce layers that persist for the whole session. On a page whose animation budget is tight, the header is sometimes the right thing to simplify.

The panel shows the current state, not the worst state. Scroll through the whole section with the panel open; layers appear and disappear as elements animate, and the peak is what the device has to accommodate.

Browser-specific notes

Everything on this page is Chromium behaviour and none of it is specified. Layer promotion heuristics, tiling policy and eviction strategy are implementation choices, and the other two engines make different ones.

The part that does generalise is the direction of the advice. Fewer layers, smaller textures and no standing will-change hints are improvements in every engine — they simply cannot be verified as precisely elsewhere. That is the useful way to use Chromium’s tooling: to find waste that is waste everywhere, rather than to predict another engine’s layer tree.

Where Chromium is actively misleading is in how much headroom it suggests. A desktop Chromium build has a generous memory ceiling, so a page can be well over what iOS Safari will tolerate while Chromium reports no problem at all. The layer count travels; the comfort does not.

Frequently Asked Questions

Is a high layer count always bad?

No — layers are what make compositor-driven animation possible, and a page with none of them has no accelerated animation. What is bad is layers that nothing is using: promotions from stale hints, from overlap cascades, and from elements that animated once at load and were never de-promoted. A page with fifteen deliberate layers is healthier than one with eight accidental ones.

Does contain: paint reduce layer count?

Not directly, but it reduces the consequences of a layer by bounding what a repaint inside it can affect, and it can stop an overlap cascade by establishing a containing context. It is worth adding to components that animate and are otherwise self-contained, for both reasons.

How much memory is too much?

There is no fixed number, because the ceiling is the device’s rather than the page’s. A practical rule is to keep the total for any one viewport under about 100 MB at the device pixel ratio you are targeting, and to treat anything above that on mobile as a problem to solve rather than a number to note.

Why does the layer count change between page loads?

Because promotion depends on what is currently animating, what is currently overlapping, and in some cases on timing. Scroll through the section the same way each time and take the peak, rather than comparing a single snapshot to another single snapshot.

Should I use the rendering flags or the Layers panel?

Both, for different questions. The rendering flags — layer borders and paint flashing — answer “is something repainting” in about five seconds, with no recording and no reading. They are the right first move whenever a section feels heavy.

The Layers panel answers “what is holding memory and why”, which is the question that follows once you know the paint behaviour is clean and the page still feels expensive. Reaching for the panel first is common and usually wastes a few minutes, because a repainting element is a bigger problem than a badly-promoted one and is faster to find.

Does the same layer appear more than once in a scroll?

It can. Layers are created and destroyed as elements begin and finish animating, so a section with several sequential effects has a layer tree that changes shape as you move through it. What matters is the peak rather than any single moment, which is why the panel should be open while you scroll rather than consulted at a standstill.

Up: Animation Performance: Engine Support Matrix