Title: CSS Containment Module Level 1
Level: 1
Shortname: css-contain
Status: REC
Date: 2022-10-25
Deadline: 2023-01-10
Prepare for TR: yes
Implementation Report: https://drafts.csswg.org/css-contain-1/implementation-report-2022-09
Work Status: completed
Group: csswg
ED: https://drafts.csswg.org/css-contain-1/
TR: https://www.w3.org/TR/css-contain-1/
Previous Version: https://www.w3.org/TR/2020/REC-css-contain-1-20201222/
Previous Version: https://www.w3.org/TR/2019/REC-css-contain-1-20191121/
Editor: Tab Atkins, Google, http://xanthir.com/contact/, w3cid 42199
Editor: Florian Rivoal, On behalf of Bloomberg, https://florian.rivoal.net/, w3cid 43241
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.
Status Text: 
This document was published by the CSS Working Group as a Recommendation using the Recommendation track. It includes proposed corrections.
Proposed corrections are marked in the document.
W3C recommends the wide deployment of this specification as a standard for the Web.
WPT Path Prefix: css/css-contain/
Include MDN Panels: no

spec: css2; urlPrefix: https://www.w3.org/TR/CSS2/
	type: property; url: visudet.html#propdef-vertical-align; text: vertical-align
	type: dfn; url: box.html#padding-edge; text: padding edge

spec: css-backgrounds-3;
	type: dfn; url: https://drafts.csswg.org/css-backgrounds-3/#corner-clipping; text: corner clipping

spec:css21; type:dfn; text:stacking context
spec:css-display-3; type:property; text:display
spec:css-ui-3; type:property; text:text-overflow
spec:css-grid-1; type:property; text:grid
spec:css-break-3; type:dfn; text:forced break
spec:css-break-3; type:dfn; text:fragmentation
spec:css-break-3; type:dfn; text:fragmentation container
spec:css-break-3; type:dfn; text:fragmentation context
spec:css-break-3; type:dfn; text:fragmented flow
spec:css21; type:value; property: height; text:auto
spec:css-sizing-4; type:property; text:aspect-ratio
spec:css-sizing-3; type:value; for:width; text:min-content
spec:css-sizing-3; type:value; for:width; text:max-content

Introduction

Value Definitions

Strong Containment: the 'contain' property

		Name: contain
		Value: none | strict | content | [ size || layout || paint ]
		Initial: none
		Inherited: no
		Applies to: See below
		Computed value: specified keyword(s)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'', and thus turns on all forms of containment for the element. In other words, it behaves the same as ''contain: size layout paint;''.. contain-strict-001.html contain-strict-002.html contain-strict-003.html contain-flexbox-outline.html

content

This value computes to ''layout paint'', and thus turns on all forms of containment except size containment for the element. In other words, it behaves the same as ''contain: layout paint;''.. contain-content-001.html contain-content-002.html contain-content-003.html contain-content-004.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

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-button-001.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

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

			<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

1. When calculating the size of [=size containment box=], it must be treated as having no contents. 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 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 contain-size-replaced-006.html contain-size-block-001.html contain-size-block-002.html contain-size-block-003.html contain-size-block-004.html contain-size-button-002.html contain-size-fieldset-003.html replaced-element-023.html replaced-element-025.html replaced-element-027.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 Then, its contents must then be laid out into the [=size containment box|containment box=]'s resolved size. Note: [=Size containment=] does not suppress baseline alignment. See [=layout containment=] for that. contain-size-baseline-001.html
   Proposed Correction 2: The way the two normative sentences above are written was somewhat ambiguous, causing implementers to have some doubts about the precise intended effects in certain cases. In order to clarify what is meant without changing the intended behavior, The CSSWG suggest replacing this first item in the list with the following two (the existing notes remain the same):

   1. The [=intrinsic sizes=] of the [=size containment box=] are determined as if the element had no content, following the same logic as when [=sizing as if empty=]. Note: This affects explicit invocations of the ''min-content'' or ''max-content'' keywords, as well as any calculation that depends on these measurement, such as sizing [=grid tracks=] into which a size contained item is placed, or if [=fit-content sizing=] the containment box's parent. 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 contain-size-replaced-006.html contain-size-block-001.html contain-size-block-002.html contain-size-block-003.html contain-size-block-004.html contain-size-button-002.html contain-size-fieldset-003.html contain-size-flex-001.html contain-size-grid-005.html contain-size-grid-006.html contain-size-inline-block-001.html contain-size-inline-block-002.html contain-size-inline-block-003.html contain-size-inline-block-004.html contain-size-inline-flex-001.html contain-size-multicol-002.html contain-size-multicol-003.html contain-size-select-elem-001.html contain-size-select-elem-002.html contain-size-select-elem-003.html contain-size-select-elem-004.html contain-size-select-elem-005.html
   2. Laying out a [=size containment box=] and its content is conceptually done in two phases:

      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

      Note: [=Size containment=] does not suppress baseline alignment. See [=layout containment=] for that. contain-size-baseline-001.html contain-size-fieldset-004.html contain-size-inline-block-001.html contain-size-inline-block-002.html contain-size-inline-block-003.html contain-size-inline-block-004.html contain-size-inline-flex-001.html

   This change has tests

   All statements in this more detailed write-up have tests in WPT. The results of these tests can be seen at the Web-Platform-Tests dashboard:

   1. contain-size-013.html
   2. contain-size-021.html
   3. contain-size-023.html
   4. contain-size-025.html
   5. contain-size-027.html
   6. contain-size-041.html
   7. contain-size-042.html
   8. contain-size-061.html
   9. contain-size-062.html
   10. contain-size-063.html
   11. contain-size-064.html
   12. contain-size-borders.html
   13. contain-size-button-001.html
   14. contain-size-fieldset-001.html
   15. contain-size-fieldset-002.html
   16. contain-size-flexbox-001.html
   17. contain-size-flexbox-002.html
   18. contain-size-grid-001.html
   19. contain-size-grid-002.html
   20. contain-size-grid-003.html
   21. contain-size-multicol-001.html
   22. contain-size-multicol-as-flex-item.html
   23. contain-size-replaced-001.html
   24. contain-size-replaced-002.html
   25. contain-size-replaced-003a.html
   26. contain-size-replaced-003b.html
   27. contain-size-replaced-003c.html
   28. contain-size-replaced-004.html
   29. contain-size-replaced-005.html
   30. contain-size-replaced-006.html
   31. contain-size-scrollbars-001.html
   32. contain-size-scrollbars-002.html
   33. contain-size-scrollbars-003.html
   34. contain-size-scrollbars-004.html
   35. contain-size-select-001.html
   36. contain-size-select-002.html
   37. replaced-element-023.html
   38. replaced-element-025.html
   39. replaced-element-027.html
   40. contain-size-block-001.html
   41. contain-size-block-002.html
   42. contain-size-block-003.html
   43. contain-size-block-004.html
   44. contain-size-button-002.html
   45. contain-size-fieldset-003.html
   46. contain-size-flex-001.html
   47. contain-size-grid-005.html
   48. contain-size-grid-006.html
   49. contain-size-inline-block-001.html
   50. contain-size-inline-block-002.html
   51. contain-size-inline-block-003.html
   52. contain-size-inline-block-004.html
   53. contain-size-inline-flex-001.html
   54. contain-size-multicol-002.html
   55. contain-size-multicol-003.html
   56. contain-size-select-elem-001.html
   57. contain-size-select-elem-002.html
   58. contain-size-select-elem-003.html
   59. contain-size-select-elem-004.html
   60. contain-size-select-elem-005.html
   61. contain-size-fieldset-004.html
   62. contain-size-inline-block-001.html
   63. contain-size-inline-block-002.html
   64. contain-size-inline-block-003.html
   65. contain-size-inline-block-004.html
   66. contain-size-inline-flex-001.html

   Also, note the insertion of a parenthetical at the very end of [[#containment-size-opt]], referencing part of this clarified text.
2. [=Size containment boxes=] are monolithic (See [[CSS-BREAK-3#possible-breaks]]). contain-size-breaks-001.html contain-size-monolithic-001.html contain-size-monolithic-002.html contain-size-multicol-004.html

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

Possible Size-Containment Optimizations

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

Paint Containment

Possible Paint-Containment Optimizations

Privacy Considerations

Security Considerations

Appendix A. Changes

Changes from the Recommendation of 22 December 2020

• Candidate Correction 1 is now marked as Proposed Correction 1.
• Candidate Correction 2 is now marked as Proposed Correction 2.
• Marked as Proposed Correction 3: Define the effects of containment on outwards propagation of properties from the HTML <{body}> element.
• Editorial tweaks:
  • Note that paint effects with non-local effects can limit certain optimization opportunities.
  • Add subsection headings for the possible optimisations
  • List cases where various types of containment do not apply at the end rather than the start of of each section, to start with the general behavior and go into exceptions later.

Changes from the Recommendation of 21 November 2019

• Marked as Candidate Correction 1: Changed how the computed values of the contain property are determined for the shortcut values.
• Marked as Candidate Correction 2: Rewrote much of the [[#containment-size]] section in more detail to clarify ambiguities about how it is meant to work, and improve the general legibility. The intended behavior is unaltered.
• Editorial tweaks:
  • Added an example and clarified a note in the [[#containment-size]] section
  • phrasing improvement in [[#containment-paint]] to use established terminology rather than ad-hoc wording with the same intended meaning
  • phrasing improvement in note in [[#containment-paint]]
  • terminology change: replace "containing box" with "containment box"

Changes from the Candidate Recommendation of 30 April 2019

• Editorial tweaks
• Drop the at-risk “style containment” feature from this specification, move it Level 2 contain-strict-011.html contain-content-011.html 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 quote-scoping-001.html quote-scoping-002.html quote-scoping-003.html quote-scoping-004.html

Changes from the Candidate Recommendation of 08 November 2018

Changes from the Candidate Recommendation of 24 May 2018

Changes from the Candidate Recommendation of 8 August 2017

• Clarify to which box paint containment clips (see tests).
• Move the interaction between containment and the bookmark-* and string-set properties to [[CSS-CONTENT-3]] (additional tests not needed, no change in behavior).
• Remove the effects of style containment on the "break-*" properties (see tests).
• Move the description of the effects of containment on regions from this specification to [[CSS-REGIONS-1]] (additional tests not needed, no change in behavior).
• Clarify the effects of style scoping on counter-set and counter-increment (see tests)
• Size layout and paint containment don't apply to internal ruby elements (see tests)
• Layout, Paint, and size containments do not apply to non-atomic inlines (see tests here and one more test here)
• Align paint containment's behavior with overflow:clip (see test)
• Elements with size containment are monolithic (see test)
• Forced breaks area allowed in elements with layout containments, but do not propagate (see tests)
• Clarify the effects of scoping to a subtree (see test)
• Clarify the effects of scoping on open/close quotes (see tests)
• Editorial clarification: replace "Becoming a formatting context" (aka "Becoming a formatting context root") with "Establish a FC" (additional tests not needed, no change in behavior)

Changes from the Working Draft of 19 April 2017

• Clarify the interaction with display: contents
• Clarify how containment works on table parts
• Move the interaction between containment and fragmentation of overflow from this specification to CSS-OVERFLOW-4

Changes from the First Public Working Draft of 21 February 2017

• Specify handling of replaced elements for size containment
• Layout containment makes element act as a containing block for absolutely positioned and fixed positioned descendants.