Modern browsers render an intricate mix of HTML, CSS, and JavaScript in milliseconds, and the usual advice still applies: simpler selectors, flatter trees with fewer children, and careful DOM manipulation. Frameworks like Vue and React shoulder part of that last burden. The contain property adds a more direct tool — a way to tell the browser which calculations it can deprioritize or skip entirely.

MDN describes it this way:

The contain CSS property allows an author to indicate that an element and its contents are, as much as possible, independent of the rest of the document tree. This allows the browser to recalculate layout, style, paint, size, or any combination of them for a limited area of the DOM and not the entire page, leading to obvious performance benefits.

The property matters most for container elements — sections, articles — rather than leaf nodes like paragraphs or links. A single-page app that inserts and removes dynamic content across the page is the canonical case. The browser cannot anticipate those changes: inserting a class, animating an element, or merely reading an element's dimensions can force a reflow and repaint. Developers, by contrast, know from the interaction design when a button click will populate a div somewhere in view, and that the fill will likely leave the rest of the page untouched. contain passes that knowledge to the browser.

The containment values

The property accepts three values, individually or combined: size, layout, and paint. Two shorthand values cover common combinations: strict and content. A style containment type exists in the spec but is not covered here; it is considered of little value and is at risk of removal. The spec also documents edge cases and rules for each value that rarely matter in practice, but are worth consulting if a result looks wrong.

Size containment

A container with size containment is treated as if it has no contents when layout is calculated: its descendants are ignored. The container is expected to have a set height and width — otherwise it collapses, and that collapsed state is what enters page layout. Once the container's size is resolved against the page, its descendants are laid out.

The optimization gain here is modest, so size is typically paired with another value. Its practical use is guarding against resize feedback loops — the container-query situation where changing descendants based on container size changes the container again, which changes the descendants, and so on. With containment, the loop is cut.

The article's demo illustrates this: a red box grows to the purple parent's size plus five pixels, a resize observer forces it to resize again, and the parent follows, until the process stops at 300 pixels. Ticking "set size containment" sets fixed dimensions on the purple box, and the red box resizes exactly once — overflowing the parent, but stopping there. A resize button shows the box still responds to explicit changes. The same behavior is possible without containment, but then every descendant change ripples through page layout instead of staying internal.

Layout containment

With layout containment, external elements cannot affect the container's internal layout, and the internal layout cannot affect external elements — so layout calculations can assume the container is isolated. Related work can also be delayed or deprioritized when the container is off-screen or obscured; the spec's example is a containing box near the end of a block container while the beginning is in view.

Two side effects deserve attention. The container becomes a containing block for absolute and fixed descendants, equivalent to applying relative position, and it gains a new stacking context, so z-index behaves as if relative, absolute, or fixed positioning were applied. Setting top, right, bottom, or left on the container itself has no effect. In the demo, toggling containment snaps absolutely positioned purple lines inside the purple box and stacks the container above the green lines.

Paint containment

paint containment promises that no child will be painted outside the container's box dimensions — similar to overflow: hidden, with differences. The container receives the same treatment as under layout containment: it becomes a containing block and gets its own stacking context, so positioned children respect it. Repeating the layout demo with paint instead produces much the same result, except the purple lines are clipped at the container's border-box rather than overflowing.

It also enables skip-painting: if the container is outside the viewport or obscured, its descendants cannot be visible either, so paint work is skipped entirely. The off-screen navigation menu that slides in on a click is the example — in its resting state, the browser does not paint its contents.

Combining containments

The three values address different parts of rendering. size says content changes will not shift positions on the page; layout says the container and the rest of the page will not affect one another's layout; paint says contents never render outside the container's bounds and can be skipped when the container is not visible. The spec allows combining them, for example layout and paint:

.el {
  contain: layout paint;
}

The spec also provides two shorthands:

ShorthandLonghand
contentlayout paint
strictlayout paint size

content will be the common choice for pages with many dynamic elements — large containers whose contents change over time or with user activity. strict suits containers with a defined size that never changes regardless of content, such as a div holding third-party advertising content at industry-defined dimensions with no DOM relationship to the rest of the page.

Measuring the effect

Performance benefits are largely invisible, living in behind-the-scenes layout and paint decisions. A simple demo toggles the font-size of an element with several children — a change that normally triggers re-layout and repaint — under the none, content, and strict values, with radio buttons switching the value applied to a central purple box. Both the CSS class change itself and the font change are potential re-layout triggers.

The test method was deliberately unscientific: pick a containment type, start a Chrome DevTools performance recording, click the button, wait for the change, stop after another second or so, three runs per type. The times are in low milliseconds but differ enough to sense the benefit, and results could shift considerably in a real-world situation. In the recording, the relevant task's event log lists recalculate style, layout, update layer tree, paint, and composite layers; summing those gives the task total. For the two containment types, the paint event appeared twice.

DevTools showing set time at 27.9 milliseconds which is the same as the total time to recalculate styles.
The event log with no containment.
DevTools showing set time at 13.8 milliseconds which is the same as the total time to recalculate styles.

Total times across three runs each:

ContainmentRun 1Run 2Run 3Average
none24 ms33.8 ms23.3 ms27.03 ms
content13.2 ms9 ms9.2 ms10.47 ms
strict5.6 ms18.9 ms8.5 ms11 ms

Layout consumed most of the time. Spikes appeared sporadically, including one much higher strict run that was kept because such variance happens in the real world. Multiply one small change by the many DOM and style changes on a typical dynamic page and the effect scales.

Layout once, paint twice

For the no-containment task, paint fired once, taking roughly 0.2 ms to 3.6 ms, and its details report that the painted area was the whole page — the viewport's dimensions — with #document as the layer root. Hovering the paint event in DevTools highlights the painted region, including the page area outside the purple box. Read the details by expanding the frame timeline, not the main one.

Showing frame details open and main details closed in DevTools.
Showing frame details open and main details closed in DevTools
Showing DevTools paint calculation of 0.7 milliseconds.
Paint event details

Layers are the browser's mechanism for elements that can overlap others through a new stacking context — the way position: relative; plus z-index: 1; promotes an element to its own layer. The contain property has the same effect, which the DevTools Rendering panel's "Layer borders" option makes visible: with none, only the typical static page layers appear; with content or strict, the purple box becomes its own layer and the surrounding layers shift, the layer line moving below the box.

Layers with no containment
Layers with containment

The doubled paint under content and strict serves two purposes: the first paints the purple box itself and reports its dimensions, the box now enjoying its own layer; the second paints the box's contents, which are scrolling elements. Because the stacking context is guaranteed, the spec explains, scrolling elements can be painted into a single GPU layer. That second event reports the taller height of the scrolling content, possibly narrower to leave room for a scrollbar, and names main.change — the purple main element — as the layer root rather than #document.

First paint event with content containment
Second paint event with content containment

This yields a scrolling optimization: scrolling elements normally must be painted when they come into view, but scrolling elements inside containment have already been painted.

The Rendering panel's "Scrolling performance issue" checkbox confirms it. With containment none, Chrome overlays the purple box with a "repaints on scroll" label.

DevTools showing “repaints on scroll” with no containment

"Paint flashing" shows the same live; note that flashing colors can be problematic for some users, particularly if the option stays enabled while visiting other sites. With paint flashing on, every scroll inside the purple box triggers a paint indicator over all its text. Switch to content or strict and scroll again: after the first initial flash the indicator does not reappear, though the scrollbar still shows paint activity while scrolling.

Paint flashing enabled and scrolling with no containment
Paint flashing and scrolling with content containment

The "repaints on scroll" overlay is also gone under both containment forms. Containment delivers gains in painting and in scrolling alike.

A transparent background breaks the paint benefits

While experimenting, one test defeated the expected behavior: a minimally styled scrolling box with lots of text, content containment applied, still carried the "repaints on scroll" overlay and painted on scroll exactly like no containment. Comparing against the styled version isolated the cause — a transparent background-color on the container suppresses the scrolling performance benefits.

A follow-up test toggling the container's background-color between transparent and the body's background color and changing the contents' font-size to force re-layout and repaint gave roughly equal results. The behind-the-scenes calculations still appear more performant; only the paint events differ. With a transparent background, the container appears not to become its own layer in paint calculations: the first run logged a single paint event, the second the two expected events. Faking transparency by matching the color behind the element works as well. The plausible explanation is that a transparent container must rely on whatever lies underneath, making separation into its own paint layer impossible.

Rendering panel with transparent background-color
Rendering panel with background-color applied

With content containment and a transparent background, the box shows "repaints on scroll" plus a green paint overlay while scrolling; with a real background, same checkboxes, neither appears — only the scrollbar shows paint activity. The takeaway: give the container some form of background color when applying containment.

Where to apply it

Which elements get contain is a judgment call, as there is no specific guidance. The general rule is container elements holding other elements, especially those with a dynamic aspect: grid areas of a CSS grid, elements containing third-party content, and containers whose content changes with user interaction. There should be no harm in these cases, provided the element does not genuinely rely on something outside the containment.

Browser support is very strong, with Safari the only holdout; the property can be used regardless, since a browser that does not understand it or its value skips the code without error.