Stop Letting One Widget Reflow the Whole Page. contain Scopes It.

Open the Performance tab, record five seconds of a dashboard with a live "3 new messages" counter in the corner, and look at the flame chart. There's a good chance you'll see a Layout block fire every time that counter ticks — not sized to one <span>, but spanning a chunk of the page that has nothing to do with it.

Nobody wrote code that does that on purpose. The browser just doesn't know any better: by default, a change anywhere in the DOM is a reason to ask whether anything outside that element needs to be measured again. A <span> updating its text could, in principle, change its own size, which could push its parent, which could push a sibling, which could ripple all the way out. The layout engine can't assume otherwise, so for anything it isn't sure about, it checks.

That's the part almost nobody profiles for, because the obvious suspect is always JavaScript.

Say the counter updates from a WebSocket message every couple of seconds, and someone notices the jank. The first instinct is almost always to blame the handler:

Sometimes that genuinely helps, if the handler is doing real work. But plenty of the time the handler is one textContent assignment, the throttle buys nothing, and the Layout block in the profiler is exactly the same width as before — because throttling how often something changes doesn't change how much the browser has to re-check each time it does. The cost was never in the JS. It was in what layout had to consider every time that one element changed.

Every element in the DOM is, by default, part of one connected layout problem. There's no built-in notion of "this subtree is self-contained" — the browser has to be conservative, because CSS gives it plenty of ways for a tiny element to affect something far away: a child wider than its parent, a negative margin, an absolutely positioned descendant escaping its ancestor, intrinsic sizing that depends on content. Any of those could be happening, so near any DOM change, the engine re-checks more than the one element that changed.

This is the part the Myth "if it's slow, profile the JS" misses: sometimes the JS is one line, and the real cost is a layout engine doing its job correctly with no boundary to stop at.

CSS containment exists to let you make that promise explicit. contain: layout tells the browser: whatever happens inside this element, it does not affect anything outside it — and nothing outside affects its internal layout either. That's not a performance hint the browser might ignore, the way will-change is; it's a contract. Once you've made it, the engine can stop checking past the boundary.

contain takes several keywords, and they compose:

Add layout paint (or content) to that counter widget's wrapper, and the Layout block in the next profile is scoped to the widget — the rest of the dashboard stops showing up in it, because the browser now has a guarantee it didn't have before.

▶️ Open the interactive playground →

Runs right in your browser — poke at it and watch the concept react live.

Here's where people get burned. contain: strict sounds like the "turn it all on" option, and size containment is the part that quietly breaks things:

Size containment means the browser computes this element's size as if it had no content — on purpose, that's the whole point, so it never has to wait on the subtree to know how much space to reserve. But "as if it had no content" means an element with no explicit width/height (or aspect-ratio) and no content to size from collapses toward zero. The widget doesn't jank anymore. It just silently stops taking up space, and you find out from a bug report, not a profiler.

The fix is to pair size containment with an explicit size:

This is exactly the trade content-visibility: auto makes for you automatically when an element scrolls off-screen — it's contain: layout style paint, plus size containment kicked in conditionally, which is why that property asks you to set a contain-intrinsic-size placeholder. contain on its own gives you the same lever with none of the training wheels: you decide which boxes get which guarantees, and you're responsible for the size one.

One more side effect worth knowing before you add this everywhere: layout, paint, content, and strict all turn the element into a new containing block for absolutely- and fixed-positioned descendants, and a new stacking context. A child using position: fixed to escape to the viewport, or a dropdown relying on position: absolute against some ancestor further up the tree, will suddenly anchor to your newly-contained box instead. That's rarely what breaks a dashboard widget — but it's exactly what breaks a modal or a tooltip if you reach for contain on a wrapper without checking what's positioned relative to it.

Most elements on most pages don't need this. A static hero section, a footer, a paragraph of text — none of it changes after paint, so there's nothing for containment to isolate it from. Containment earns its keep specifically where something changes on its own schedule independent of the rest of the page: live counters, chat widgets, auto-refreshing tickers, anything driven by a timer or a socket rather than user navigation. If you haven't opened the Performance tab and actually seen a Layout block wider than the element that triggered it, you don't have evidence containment will help — you have a hunch, and contain: strict on a hunch is how an element quietly collapses to zero height.

The layout engine isn't being wasteful when it re-checks more than you expected — it's being correct, given that it has no way to know your widget is self-contained. contain is how you tell it. Scope it to the one element that changes on its own, pick layout paint (or content) first, and only reach for size / strict once that element has an explicit size to fall back on. The profiler cost that looked like a JavaScript problem was a missing boundary the whole time.

Go record a profile on the one thing on your page that updates without a page reload — a counter, a ticker, a live status dot — and check whether the Layout block is scoped to it. What did you find?

Think it clicked? Take the 8-question quiz →

Instant feedback, a hint on every question, and an explanation for each answer — right or wrong.

🚀 Want more like this? Every guide, playground, and quiz lives on bestpractic.org — open it and sign up free so the next one finds you.

Thanks for reading! Let's stay connected: