Title: CSS Containment Module Level 2
Level: 2
Shortname: css-contain
Status: ED
Work Status: stable
Group: csswg
ED: https://drafts.csswg.org/css-contain-2/
Previous Version: https://www.w3.org/TR/2022/WD-css-contain-2-20220917/
Previous Version: https://www.w3.org/TR/2020/WD-css-contain-2-20201216/
Previous Version: https://www.w3.org/TR/2020/WD-css-contain-2-20200603/
Previous Version: https://www.w3.org/TR/2019/WD-css-contain-2-20191111/
Previous Version: https://www.w3.org/TR/2019/WD-css-contain-2-20191015/
TR: https://www.w3.org/TR/css-contain-2/
Editor: Tab Atkins, Google, http://xanthir.com/contact/, w3cid 42199
Editor: Florian Rivoal, On behalf of Bloomberg, https://florian.rivoal.net/, w3cid 43241
Editor: Vladimir Levin, Google, vmpstr@google.com, w3cid 75295
Abstract: This CSS module describes the 'contain' property, which indicates that the element's subtree is independent of the rest of the page. This enables heavy optimizations by user agents when used well.
Test Suite: https://test.csswg.org/harness/results/css-contain-1_dev/
WPT Path Prefix: css/css-contain/

spec:css-display-3; type:property; text:display
spec:css-ui-3; type:property; text:text-overflow
spec:css-ui-4; type:property; text:pointer-events
spec:css-grid-1; type:property; text:grid
spec:css-break-3; type:dfn;
	text:forced break
	text:fragmentation
	text:fragmentation container
	text:fragmentation context
	text:fragmented flow
spec:css-sizing-4; type:property;
	text:contain-intrinsic-size
	text:aspect-ratio
spec:intersection-observer; type:dfn; text:intersection root
spec:css-sizing-3;
	type:value;
		for:height; text:auto
		for:width; text:min-content
		for:width; text:max-content
	type:property;
		text:width
		text:height

Introduction

Module Interactions

Value Definitions

Strong Containment: the 'contain' property

		Name: contain
		Value: none | strict | content | [ [size | inline-size] || layout || style || paint ]
		Initial: none
		Inherited: no
		Applies to: See below
		Computed value: the keyword ''contain/none'' or one or more of ''size'', ''layout'', ''paint''
		Animation type: not animatable
	

User agents are expected to support this property on all media, including non-visual ones.

none

This value indicates that the property has no effect. The element renders as normal, with no containment effects applied.

strict

This value computes to ''size layout paint style'', and thus turns on all forms of containment for the element. contain-strict-001.html contain-strict-002.html contain-strict-003.html contain-strict-011.html contain-flexbox-outline.html

content

This value computes to ''layout paint style'', and thus turns on all forms of containment except size containment for the element. contain-content-001.html contain-content-002.html contain-content-003.html contain-content-004.html contain-content-011.html Note: ''contain: content'' is reasonably "safe" to apply widely; its effects are fairly minor in practice, and most content won't run afoul of its restrictions. However, because it doesn't apply size containment, the element can still respond to the size of its contents, which can cause layout-invalidation to percolate further up the tree than desired. Use ''contain: strict'' when possible, to gain as much containment as you can.

size

The value turns on size containment for the element. This ensures that the [=size containment box|containment box=] can be laid out without needing to examine its descendants. contain-size-001.html contain-size-002.html contain-size-003.html contain-size-004.html contain-size-005.html contain-size-006.html contain-size-007.html contain-size-008.html contain-size-009.html contain-size-010.html contain-size-011.html contain-size-012.html contain-size-012b.html contain-size-013.html contain-size-021.html contain-size-023.html contain-size-025.html contain-size-027.html contain-size-041.html contain-size-042.html contain-size-051.html contain-size-052.html contain-size-056.html contain-size-061.html contain-size-062.html contain-size-063.html contain-size-baseline-001.html contain-size-borders.html contain-size-breaks-001.html contain-size-button-001.html contain-size-fieldset-001.html contain-size-fieldset-002.html contain-size-flexbox-001.html contain-size-flexbox-002.html contain-size-grid-001.html contain-size-grid-002.html contain-size-grid-003.html contain-size-grid-004.html contain-size-grid-005.html contain-size-grid-006.html contain-size-monolithic-001.html contain-size-monolithic-002.html contain-size-multicol-001.html contain-size-multicol-as-flex-item.html contain-size-replaced-001.html contain-size-replaced-002.html contain-size-replaced-003a.html contain-size-replaced-003b.html contain-size-replaced-003c.html contain-size-replaced-004.html contain-size-replaced-005.html contain-size-replaced-006.html contain-size-replaced-007.html contain-size-select-001.html contain-size-select-002.html contain-size-scrollbars-001.html contain-size-scrollbars-002.html contain-size-scrollbars-003.html contain-size-scrollbars-004.html contain-layout-size-003.html contain-paint-size-001.html contain-paint-size-002.html contain-paint-size-003.html contain-size-removed.html contain-size-dynamic-001.html contain-size-grid-indefinite-height-min-height-flex-row.html contain-size-grid-stretches-auto-rows.html

inline-size

This value turns on [=inline-size containment=] for the element. This prevents the [=inline-size=] of its [=principal box=] from directly depending on its contents. contain-inline-size-bfc-floats-001.html contain-inline-size-bfc-floats-002.html contain-inline-size-fieldset.html contain-inline-size-flex.html contain-inline-size-flexitem.html contain-inline-size-grid.html contain-inline-size-intrinsic.html contain-inline-size-legend.html contain-inline-size-multicol.html contain-inline-size-regular-container.html contain-inline-size-removed.html contain-inline-size-replaced.html contain-inline-size-table.html contain-inline-size-vertical-rl-.html contain-inline-size-grid-indefinite-height-min-height-flex-row.html contain-inline-size-grid-stretches-auto-rows.html Note: There can still be indirect dependencies, see [[#containment-inline-size]].

layout

This value turns on layout containment for the element. This ensures that the [=layout containment box|containment box=] is totally opaque for layout purposes; nothing outside can affect its internal layout, and vice versa. contain-layout-001.html contain-layout-002.html contain-layout-003.html contain-layout-004.html contain-layout-005.html contain-layout-006.html contain-layout-007.html contain-layout-009.html contain-layout-010.html contain-layout-011.html contain-layout-012.html contain-layout-013.html contain-layout-014.html contain-layout-016.html contain-layout-017.html contain-layout-018.html contain-layout-019.html contain-layout-020.html contain-layout-021.html contain-layout-baseline-001.html contain-layout-baseline-002.html contain-layout-baseline-003.html contain-layout-baseline-004.html contain-layout-baseline-005.html contain-layout-breaks-001.html contain-layout-breaks-002.html contain-layout-cell-001.html contain-layout-cell-002.html contain-layout-flexbox-001.html contain-layout-grid-001.html contain-layout-ifc-022.html contain-layout-independent-formatting-context-001.html contain-layout-independent-formatting-context-002.html contain-layout-independent-formatting-context-003.html contain-layout-ink-overflow-013.html contain-layout-ink-overflow-014.html contain-layout-ink-overflow-015.html contain-layout-ink-overflow-016.html contain-layout-ink-overflow-017.html contain-layout-ink-overflow-018.html contain-layout-ink-overflow-019.html contain-layout-ink-overflow-020.html contain-layout-size-003.html contain-subgrid-001.html contain-layout-dynamic-001.html contain-layout-dynamic-004.html contain-layout-dynamic-005.html

style

This value turns on style containment for the element. This ensures that, for properties which can have effects on more than just an element and its descendants, those effects don't escape the element. contain-style-baseline-001.html contain-style-breaks-001.html contain-style-breaks-002.html contain-style-breaks-003.html contain-style-breaks-004.html contain-style-breaks-005.html contain-style-counters-001.html contain-style-counters-002.html contain-style-counters-003.html contain-style-counters-004.html contain-style-counters-005.html contain-style-ol-ordinal-li-container.html contain-style-ol-ordinal-pseudo-reversed.html contain-style-ol-ordinal-pseudo.html contain-style-ol-ordinal-reversed.html contain-style-ol-ordinal-start-reversed.html contain-style-ol-ordinal-start.html contain-style-ol-ordinal.html counter-scoping-001.html counter-scoping-002.html counter-scoping-003.html counter-scoping-004.html quote-scoping-001.html quote-scoping-002.html quote-scoping-003.html quote-scoping-004.html quote-scoping-invalidation-001.html quote-scoping-invalidation-002.html quote-scoping-invalidation-003.html quote-scoping-invalidation-004.html contain-style-dynamic-001.html

paint

This value turns on paint containment for the element. This ensures that the descendants of the [=paint containment box|containment box=] don't display outside its bounds, so if an element is off-screen or otherwise not visible, its descendants are also guaranteed to be not visible. contain-paint-001.html contain-paint-002.html contain-paint-004.html contain-paint-005.html contain-paint-006.html contain-paint-007.html contain-paint-008.html contain-paint-009.html contain-paint-010.html contain-paint-011.html contain-paint-012.html contain-paint-014.html contain-paint-015.html contain-paint-016.html contain-paint-017.html contain-paint-018.html contain-paint-019.html contain-paint-020.html contain-paint-021.html contain-paint-022.html contain-paint-023.html contain-paint-024.html contain-paint-025.html contain-paint-047.html contain-paint-048.html contain-paint-baseline-001.html contain-paint-cell-001.html contain-paint-cell-002.html contain-paint-clip-011.html contain-paint-clip-012.html contain-paint-clip-013.html contain-paint-clip-014.html contain-paint-clip-015.html contain-paint-clip-016.html contain-paint-clip-017.html contain-paint-clip-018.html contain-paint-clip-019.html contain-paint-ifc-011.html contain-paint-independent-formatting-context-001.html contain-paint-independent-formatting-context-002.html contain-paint-independent-formatting-context-003.html contain-paint-size-001.html contain-paint-size-002.html contain-paint-size-003.html contain-paint-table-001.html contain-paint-table-002.html contain-subgrid-001.html contain-paint-change-opacity.html contain-paint-dynamic-001.html contain-paint-dynamic-002.html contain-paint-dynamic-003.html contain-paint-dynamic-004.html contain-paint-dynamic-005.html

			<body>
				<aside>...</aside>
				<section>
					<h2>Messages</h2>
					<article>
						Lol, check out this dog: images.example.com/jsK3jkl
					</article>
					<article>
						I had a ham sandwich today. #goodtimes
					</article>
					<article>
						I have political opinions that you need to hear!
					</article>
					…
				</section>
			</body>
		

Types of Containment

Size Containment

Sizing as if empty

The [=used value|used=] 'width' and 'height' of the [=size containment box|containment box=] are determined as if performing a normal layout of the box, except that it is treated as having no content-- not even through pseudo elements such as ''::before'', ''::after'', or ''::marker''. contain-size-021.html contain-size-023.html contain-size-025.html contain-size-027.html contain-size-061.html contain-size-062.html contain-size-063.html contain-size-borders.html contain-size-fieldset-001.html contain-size-fieldset-002.html contain-size-select-001.html contain-size-select-002.html contain-size-scrollbars-001.html contain-size-scrollbars-002.html contain-size-scrollbars-003.html contain-size-scrollbars-004.html contain-size-button-001.html contain-size-flexbox-001.html contain-size-flexbox-002.html contain-size-grid-001.html Replaced elements must be treated as having a [=natural dimensions|natural=] width and height of 0 and no [=natural aspect ratio=]. Note: Size containment only suppresses the [=natural aspect ratio=], so properties like 'aspect-ratio' which affect that [=preferred aspect ratio=] directly are honored. contain-size-013.html contain-size-041.html contain-size-042.html contain-size-replaced-001.html contain-size-replaced-002.html contain-size-replaced-003a.html contain-size-replaced-003b.html contain-size-replaced-003c.html contain-size-replaced-004.html contain-size-replaced-005.html replaced-element-023.html replaced-element-025.html replaced-element-027.html All CSS properties of the [=size containment box=] are taken into account as they would be when performing layout normally. Other specifications may make specific exemptions. contain-size-replaced-006.html Note: Even when the element's [=sizing properties=] specify an intrinsic size, this does not necessarily make the element zero-sized: properties set on the element itself continue to be taken into account, which can cause it to be larger. contain-size-grid-002.html contain-size-grid-003.html contain-size-multicol-001.html contain-size-multicol-as-flex-item.html

Laying out in-place

The [=size containment box|containment box=]'s content (including any pseudo-elements) must then be laid out into the now fixed-size [=size containment box|containment box=] normally. contain-size-064.html

		img {
			width: 100px;
			aspect-ratio: 1/1;
			contain: size;
		}
		
		<img src="https://www.example.com/300x100.jpg">
		

Possible Size-Containment Optimizations

Inline-Size Containment

Layout Containment

				<article>Lorem ipsum…</article>
				<div id=a></div>
				<aside>
				  <div id=b></div>
				  <div id=c></div>
				</aside>
				<aside>
				  <div id=d></div>
				  <div id=e></div>
				</aside>
				<div id=f></div>
			

				article {flow-into: foo;}
				#a, #b, #c, #d, #e, #f {flow-from: foo;}
				aside {contain: layout}
			

Possible Layout-Containment Optimizations

Style Containment

			body {
				counter-reset: foo;
			}
			div {
				counter-increment: foo;

				/* and to help observe nesting properly */
				margin: .2em;
				padding: .2em;
				background: #0001;
			}
			div::before {
				content: counters(foo, ".");
			}
		

Possible Style-Containment Optimizations

Paint Containment

Possible Paint-Containment Optimizations

	Name: content-visibility
	Value: visible | auto | hidden
	Initial: visible
	Inherited: no
	Applies to: elements for which [=size containment=] can apply
	Animation type: see [[#content-visibility-animation]]
	

: visible :: No effect. The element's contents are laid out and rendered as normal. content-visibility/content-visibility-002.html content-visibility/content-visibility-012.html content-visibility/content-visibility-013.html content-visibility/content-visibility-014.html content-visibility/content-visibility-023.html content-visibility/content-visibility-024.html content-visibility/content-visibility-025.html content-visibility/content-visibility-042.html content-visibility/content-visibility-052.html content-visibility/content-visibility-057.html content-visibility/content-visibility-with-top-layer-003.html : hidden :: The element [=skips its contents=]. content-visibility/content-visibility-001.html content-visibility/content-visibility-003.html content-visibility/content-visibility-004.html content-visibility/content-visibility-005.html content-visibility/content-visibility-006.html content-visibility/content-visibility-007.html content-visibility/content-visibility-008.html content-visibility/content-visibility-009.html content-visibility/content-visibility-010.html content-visibility/content-visibility-011.html content-visibility/content-visibility-015.html content-visibility/content-visibility-016.html content-visibility/content-visibility-017.html content-visibility/content-visibility-018.html content-visibility/content-visibility-019.sub.https.html content-visibility/content-visibility-020.html content-visibility/content-visibility-021.html content-visibility/content-visibility-022.html content-visibility/content-visibility-026.html content-visibility/content-visibility-028.html content-visibility/content-visibility-029.html content-visibility/content-visibility-030.html content-visibility/content-visibility-031.html content-visibility/content-visibility-032.html content-visibility/content-visibility-033.sub.https.html content-visibility/content-visibility-034.html content-visibility/content-visibility-036.html content-visibility/content-visibility-037.html content-visibility/content-visibility-038.html content-visibility/content-visibility-039.html content-visibility/content-visibility-040.html content-visibility/content-visibility-041.html content-visibility/content-visibility-043.html content-visibility/content-visibility-044.html content-visibility/content-visibility-045.html content-visibility/content-visibility-072.html content-visibility/content-visibility-078.html content-visibility/content-visibility-082.html content-visibility/content-visibility-canvas.html content-visibility/content-visibility-forced-layout-client-rects.html content-visibility/content-visibility-img.html content-visibility/content-visibility-input-image.html content-visibility/content-visibility-svg.html content-visibility/content-visibility-video.html content-visibility/content-visibility-fieldset-size.html content-visibility/content-visibility-with-top-layer-000.html content-visibility/content-visibility-with-top-layer-001.html content-visibility/content-visibility-with-top-layer-002.html content-visibility/document-element-computed-style.html content-visibility/element-reassigned-to-skipped-slot.html content-visibility/element-reassigned-to-slot-in-skipped-subtree.html content-visibility/scrollIntoView-target-with-contents-hidden.html content-visibility/scrollIntoView-with-focus-target-with-contents-hidden.html content-visibility/content-visibility-with-top-layer-hide-after-addition.html content-visibility/dynamic-change-paint-fully-obscuring-child-001.html The [=skipped contents=] must not be accessible to user-agent features, such as find-in-page, tab-order navigation, etc., nor be selectable or focusable. content-visibility/content-visibility-035.html content-visibility/content-visibility-047.html content-visibility/content-visibility-056.html content-visibility/content-visibility-060.html content-visibility/content-visibility-061.html content-visibility/content-visibility-067.html content-visibility/content-visibility-083.html content-visibility/content-visibility-084.html Note: This is similar to giving the contents ''display: none''. content-visibility/content-visibility-041.html : auto :: Changes the [=used value=] of the 'contain' property so as to turn on [=layout containment=], [=style containment=], and [=paint containment=] for the element. content-visibility/content-visibility-026.html content-visibility/content-visibility-027.html content-visibility/content-visibility-074.html content-visibility/content-visibility-auto-in-iframe.html content-visibility/content-visibility-auto-intrinsic-width.html content-visibility/content-visibility-auto-state-changed-first-observation.html content-visibility/content-visibility-auto-state-changed-removed.html content-visibility/content-visibility-auto-state-changed.html content-visibility/content-visibility-with-top-layer-005.html content-visibility/content-visibility-with-top-layer-006.html If the element is not [=relevant to the user=], it also [=skips its contents=]. content-visibility/content-visibility-046.html content-visibility/content-visibility-050.html content-visibility/content-visibility-058.html content-visibility/content-visibility-064.html content-visibility/content-visibility-068.html content-visibility/content-visibility-072.html content-visibility/content-visibility-079.html content-visibility/content-visibility-with-top-layer-003.html content-visibility/content-visibility-auto-state-changed-first-observation.html content-visibility/content-visibility-auto-state-changed.html Unlike ''content-visibility/hidden'', the [=skipped contents=] must still be available as normal to user-agent features such as find-in-page, tab order navigation, etc., and must be focusable and selectable as normal. content-visibility/content-visibility-048.html content-visibility/content-visibility-049.html content-visibility/content-visibility-050.html content-visibility/content-visibility-053.html content-visibility/content-visibility-054.html content-visibility/content-visibility-055.html content-visibility/content-visibility-058.html content-visibility/content-visibility-062.html content-visibility/content-visibility-063.html content-visibility/content-visibility-064.html content-visibility/content-visibility-065.html content-visibility/content-visibility-066.html content-visibility/content-visibility-068.html content-visibility/content-visibility-070.html content-visibility/content-visibility-071.html content-visibility/content-visibility-075.html content-visibility/content-visibility-076.html

Animating and Interpolating 'content-visibility'

Using ''content-visibility: hidden''

Using ''content-visibility: auto''

[Exposed=Window]
interface ContentVisibilityAutoStateChangeEvent : Event {
	constructor(DOMString type, optional ContentVisibilityAutoStateChangeEventInit eventInitDict = {});
	readonly attribute boolean skipped;
};
dictionary ContentVisibilityAutoStateChangeEventInit : EventInit {
	boolean skipped = false;
};

Privacy Considerations

Security Considerations

Appendix A. Changes

Changes from 2022-09-17 Working Draft

Changes from 2020-12-16 Working Draft

Changes from 2020-06-03 Working Draft

Changes from 2019-11-11 Working Draft

Changes from CSS Containment Level 1