contain

The contain property in CSS indicates to the browser that the element and its descendants are considered independent of the document tree as much as possible. This potentially provides performance benefits with calculations in layout, style, paint, size, or any combination for a limited area of the DOM and not the entire page.

The property has five standard values and two shorthand values that combine variations of the standard values. Each value has some unique and shared benefits depending on the context of the element that applies them.

The typical use of this property is an element that contains content of some type. Consider a widget that renders the incoming data that changes the layout and visuals of the element’s descendants. Another element to consider is one that contains the results of third-party data, such as a banner ad, where the benefits of containment let us either de-prioritize painting certain content, how to handle sizing the content that’s received, or determine whether content should even be visible. A mostly static site, on the other hand, will receive little benefit other than the first layout and paint to the screen on page load.

Syntax

div {
  contain: none | strict | content | [ size || layout || style || paint ];
}

div {
  contain: none; /* no containment on element */
  contain: layout; /* influences how element relates to other elements in the document */
  contain: paint; /* influences how element is painted to screen */
  contain: size; /* influences how element affects size calculations for the page */
  contain: style; /* is considered at-risk for removal from spec */


  contain: content; /* combines layout and paint */
  contain: strict; /* combines layout, paint, and size */
}

Property values

Layout

The layout containment value informs the browser that none of the element’s descendants affect other elements on the page, nor do those other elements have any effect on the descendants of the contained element. This allows the browser to potentially reduce the number of calculations necessary when creating the page layout

Another benefit is that if the contained element is off-screen or obscured in some way, then the browser may delay or shift related calculations to a lower priority. An example of this is a contained element not in view at the end of a block element and the beginning of that block element is visible.

An element with layout containment becomes a containing box for positioned descendants — such as elements with absolute positioning. The element receives a new stacking context in relation to the page and the z-index property can be used. Although, directional properties, such as top or left, do not apply.

Even though the descendants of the contained element may not influence other elements on the page, they can still influence their contained ancestor element. For example, a descendant can cause the contained element to resize in reaction to changes. In that case, the contained element can still potentially influence other elements on the page but the descendants will still not be involved in those calculations.

The following demo provides a simple explanation for what happens when the layout containment is applied. When clicking each of the top boxes the containment is applied and the red arrows will change appearance. The appearance of the red arrows suggests whether the descendants of the box affect the other boxes on the page during layout calculations.

Paint

The paint containment value informs the browser that none of the descendants of the element will be painted outside of the border-box of the element. If a descendant element is positioned to have a portion of its bounding box to be clipped by the contained element’s border-box then that portion shall not be painted. If a descendant element is positioned fully outside the contained element’s border-box then it is not painted at all. This is similar to applying overflow: hidden; to the element, but without the benefits of skipping or reducing needed calculations.

Another benefit is that if the contained element is not visible in some way within the viewport, then it may skip the descendants of the element when performing painting calculations. An example of this is an element that’s placed off the page to the left of the viewport. If the contained element is not visible, then it’s a guarantee that its contents will not be visible. Therefore, they are not required to be involved in paint calculations.

An element with the paint containment also becomes a containing box for positioned descendants — such as elements with absolute positioning. The element also receives a new stacking context in relation to the page and the z-index property can be used. Although, directional properties, such as top or left, do not apply.

A scrolling element may get additional benefits by having its descendants placed in a new paint layer that can assist with scrolling performance. Normally, scrolling elements can cause constant repaints as the descendants appear and disappear during scrolling. A scrolling element with the paint containment can potentially skip this constant repainting of scrolling descendants.

The following demo provides a simple explanation for what happens when the paint containment is applied. Click anywhere to toggle the containment on the purple box. When containment is applied some of the green boxes change in appearance. The appearance of the green boxes shows how they are painted or not painted.

Size

The size containment value informs the browser that none of the descendants need to be considered when performing layout calculations for the page. The contained element must have height and width properties applied, or it will collapse to zero pixels square. Only the element itself needs to be considered for page layout calculations as descendants cannot influence the size of the element. The contained element’s descendants are completely skipped in such calculations; as if it had no descendants at all.

For full benefits of optimization, the size containment is usually applied with other containment types.

An element with the size containment receives a new stacking context in relation to the page and the z-index property can be used. Although, directional properties, such as top or left, do not apply.

The following demo provides a simple explanation for what happens when size containment is applied. Click anywhere to toggle the containment on the purple box. When the containment is applied the purple box changes in size. By default the purple box’s height is defined by its children, but with containment the height must be defined. Once containment is applied, the descendants are not longer involved in size related layout calculations.

Style

The style containment value informs the browser that some CSS properties, such as counters and quotes, will be scoped to the contained element. 

The counter-increment and counter-set properties must be scoped to the contained element’s sub-tree. If extended outside the contained element then a new counter is created.

The content property’s values of open-quote, close-quote, no-open-quote, and no-close-quote must be scoped to the contained element’s sub-tree.

This containment value is considered at-risk of being removed from the specification.

Content

The content containment value is a combination of both the layout and paint containment values. This is the equivalent of applying containment in this manner:

div {
  contain: layout paint;
}

All the potential benefits described above for each value would then be available to the contained element. This containment would be considered relatively safe to apply widely to multiple elements on the page.

Strict

The strict containment value is a combination of the layout, paint, and size containment values. This is the equivalent of applying containment in this manner:

div {
  contain: layout paint size;
}

All the potential benefits described above for each value would then be available to the contained element.

As the “strictest” of the containment values, this value should be used with careful consideration. This is due to the dimension requirements it imposes on the contained element. With these requirements, this containment value does offer the most potential performance benefits of containment.

Browser support

Other resources

• CSS Contain Module Level 1
• CSS Contain Module Level 2
• MDN Contain Property
• MDN CSS Containment