How to Use the CSS contain Property

The CSS contain property tells the browser that selected parts of an element’s rendering can be handled independently from the rest of the document. Choose the smallest set of containment types that matches the component: use layout to isolate layout, paint to clip painting at the component boundary, and size containment only when the component can have a size independent of its children.

For a typical self-contained widget, start with contain: content;. It enables layout, paint, and style containment, but not size containment. Check for clipped overflow and changes to positioned descendants before using it. For a component whose width is independent of its content, consider contain: inline-size; instead.

What CSS containment does

MDN describes contain as indicating that an element and its contents are, as much as possible, independent from the rest of the document tree. This lets the browser limit some layout, style, paint, or size calculations to a subtree. It is a declaration about how the component behaves, not a universal performance switch; profile the page to see whether it helps. MDN’s contain reference

Containment is useful for components with clear boundaries, especially when their internal content changes often. It does not guarantee that updates are cheap: if the component’s own dimensions depend on its children, content changes can still require the browser to recalculate its size.

Choose the right contain value

Value	What it contains	When to consider it
none	Nothing	The default behavior; use to remove containment.
layout	Layout	The component’s internal layout can be isolated, but its overflow must remain visible.
paint	Painting	Descendants should not paint outside the component’s bounds. Overflow is clipped.
size	Size in both inline and block directions	The component’s dimensions do not depend on its children. Provide a useful size.
inline-size	Size in the inline direction	The component’s inline size can be computed independently of its content.
style	Relevant style effects, such as CSS counters	Those effects should be scoped to the component. This is not general CSS style scoping like Shadow DOM or @scope.
content	layout paint style	A common starting point for an independent component that should not be size-contained.
strict	size layout paint style	The component can be isolated in all these ways and has an appropriate independent size.

You can combine compatible values, for example contain: layout paint or contain: inline-size layout. Do not combine size with inline-size. The content shorthand excludes size containment; strict includes it.

Apply containment safely

1. Identify the component boundary. Choose a subtree whose behavior you can describe independently of the surrounding page.
2. Write down what must remain outside. Check for menus, tooltips, focus rings, shadows, sticky content, and absolutely or fixed-positioned children.
3. Start with the smallest value. Try layout if layout isolation is the goal. Add paint only if clipping overflow is acceptable. Use content when layout, paint, and style containment all fit.
4. Set dimensions for size containment. If using size or strict, give the component a deliberate size or a useful intrinsic placeholder size.
5. Compare behavior and rendering. Check the component at its target viewport sizes and with representative content, including long text and expanded controls.

<section class="results-panel">
  <h2>Search results</h2>
  <div class="results-panel__body">...</div>
</section>

/* Isolate layout, paint, and relevant style effects. */
.results-panel {
  contain: content;
}

/* If child content should not determine the inline size: */
.results-panel--fixed-inline-size {
  inline-size: 24rem;
  contain: inline-size layout;
}

/* If both dimensions are independent, give the box a usable size. */
.results-panel--fixed-size {
  inline-size: 24rem;
  block-size: 18rem;
  contain: strict;
}

These examples show valid declarations, but the right value depends on the component’s intended sizing and overflow. A fixed size may need responsive rules in a real layout.

Know the side effects before shipping

Applying layout, paint, content, or strict creates a containing block for absolutely and fixed-positioned descendants, a stacking context, and a block formatting context. These changes can affect where positioned children appear and how their z-index stacks with neighboring content.

Paint containment clips descendant painting at the containing bounds. A dropdown, tooltip, shadow, or other effect that extends beyond the box may be cut off. If overflow must escape the component, do not use paint containment on that boundary; consider whether layout-only containment meets the goal.

Size containment changes the sizing contract: the element’s size is computed independently of its children. The box can have no useful dimensions unless you specify them. The size and inline-size values are mutually exclusive.

Style containment does not isolate all CSS rules. It scopes relevant effects such as counters; it is not a substitute for Shadow DOM or @scope.

Related properties: content-visibility and intrinsic size

contain establishes independence for selected aspects of a subtree. content-visibility controls whether an element’s contents are rendered and can let the browser defer rendering work until needed. contain-intrinsic-size supplies a placeholder size when size containment would otherwise leave the layout without useful dimensions.

.article-section {
  content-visibility: auto;
  contain-intrinsic-size: auto 32rem;
}

This example lets the browser skip rendering work for off-screen content where supported and supplies an estimated block size for layout. Pick a placeholder that is reasonable for the content; a poor estimate can cause visible layout shifts as content is rendered. See MDN’s contain-intrinsic-size reference and MDN’s guide to CSS containment.

Performance, browser support, and reliability

Containment can reduce the area the browser needs to reconsider during rendering updates, particularly when a dynamic component is genuinely independent. It does not guarantee a speedup, and it cannot eliminate work needed to compute the component’s own size when that size depends on its children. Measure the actual page before and after the change using the same interactions and content; do not infer a performance gain from the declaration alone.

MDN marks contain as Baseline and widely available since March 2022. The reference notes that it follows the latest CSS Containment Module Level 2 syntax and that not every part may be implemented in every browser. Check the specific value against your project’s browser targets. MDN browser support and reference

For dependable behavior, test target browsers and states that exercise overflow, stacking, and sizing: open menus, show tooltips, load long content, resize the viewport, and update the component dynamically. Keep containment only where those behaviors match the component contract.

Or skip the browser setup

If you need screenshots to inspect a page with CSS changes, ScreenshotNeo is a website screenshot API and MCP server for developers. One GET request returns an image or PDF. The DIY option is to capture the page with a browser tool after applying your CSS; ScreenshotNeo avoids setting up and running that browser capture flow.

curl -G "https://api.screenshotneo.com/v1/shot" \
  -d access_key=YOUR_API_KEY \
  --data-urlencode url=https://stripe.com \
  -o shot.webp

See the ScreenshotNeo API documentation for request options. Cookie banners, popups, and chat widgets are removed before the shot. Bot checks, blank pages, and failed loads are never billed. An MCP server lets AI agents take screenshots. The free plan includes 1,000 screenshots a month with no card; paid plans start at $5 for 3,000.

Sign up free for ScreenshotNeo and get 1,000 screenshots a month with no card.

Troubleshooting

Symptom	Likely cause	What to do
A dropdown or tooltip is cut off	paint, content, or strict clips painting at the component boundary.	Remove paint containment from that boundary or move the overlay outside the clipped component.
A positioned child moves or appears behind another element	Layout containment creates a containing block and stacking context.	Review its positioning ancestor and stacking order; adjust the component structure or remove containment if the new boundary is wrong.
The contained element collapses or has unexpected dimensions	size or strict makes sizing independent of children.	Set explicit or otherwise appropriate dimensions, or use a value without size containment.
Content changes still cause layout work	The component’s own dimensions depend on its children, or the changed work is outside the contained subtree.	Check which dimensions and effects depend on children; containment does not make all updates free.
CSS counters behave differently	style containment scopes relevant effects such as counters.	Check counter scope and whether style containment belongs on this component.
A value behaves differently in a target browser	Support can differ for individual parts of the syntax.	Check the specific value in current browser support data and test the project’s target browsers.

FAQ

Should I use contain: strict everywhere?

No. It includes size containment and can make a component size as though it had no children. Apply it only when the component has an appropriate independent size and the other containment effects are intended.

Does contain: content include size containment?

No. It is shorthand for layout paint style. The strict shorthand adds size containment.

Does contain: style scope all CSS?

No. It scopes relevant effects such as CSS counters, not general selectors or styles in the way Shadow DOM or @scope can.

How do I know whether containment improved performance?

Profile representative page interactions before and after applying the smallest suitable value. There is no general performance percentage: results depend on the page and the work being isolated.