Overview.bs

<pre class=metadata>
Title: CSS Containment Module Level 3
Level: 3
Shortname: css-contain
Status: ED
Work Status: Exploring
Group: csswg
ED: https://drafts.csswg.org/css-contain-3/
TR: https://www.w3.org/TR/css-contain-3/
Editor: Tab Atkins, Google, http://xanthir.com/contact/, w3cid 42199
Editor: Florian Rivoal, On behalf of Bloomberg, https://florian.rivoal.net/, w3cid 43241
Editor: Miriam E. Suzanne, Invited Expert, http://miriamsuzanne.com/contact, w3cid 117151
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/
</pre>
<pre class=link-defaults>
spec:css2; type:dfn; text:stacking context
spec:css2; type:property; text:content
spec:css-display-3; type:property; text:display
spec:css2; type:property; text:counter-increment
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:css-contain-2; type:dfn; text:layout containment box
spec:css-contain-2; type:dfn; text:size containment box
spec:css-sizing-4; type:property; text:contain-intrinsic-size
spec:css-sizing-4; type:property; text:aspect-ratio
spec:intersection-observer; type:dfn; text:intersection root
spec:css-sizing-3; type:value; for:height; text:auto
spec:css-sizing-3; type:property; text:width
spec:css-sizing-3; type:dfn; text:width
spec:css-sizing-3; type:property; text:height
spec:css-sizing-3; type:dfn; text:height
spec:css-sizing-3; type:dfn; text:size
spec:css-sizing-3; type:value; for:width; text:min-content
spec:css-sizing-3; type:value; for:width; text:max-content
spec:css-syntax-3; type:dfn; text:identifier
spec:css-values-4; type:dfn; text:relative length
</pre>

<h2 id='intro'>
Introduction</h2>

	Issue: This is a diff spec over <a href="https://www.w3.org/TR/css-contain-2/">CSS Containment Level 2</a>.
	It is currently an Exploratory Working Draft:
	if you are implementing anything, please use Level 2 as a reference.
	We will merge the Level 2 text into this draft once it reaches CR.

<h3 id="interaction">
Module Interactions</h3>

	This document defines new features not present in earlier specifications.
	In addition, it aims to replace and supersede [[!CSS-CONTAIN-1]]
	once stable.

<h3 id="values">
Value Definitions</h3>

	This specification follows the <a href="https://www.w3.org/TR/CSS2/about.html#property-defs">CSS property definition conventions</a> from [[!CSS2]]
	using the <a href="https://www.w3.org/TR/css-values-3/#value-defs">value definition syntax</a> from [[!CSS-VALUES-3]].
	Value types not defined in this specification are defined in CSS Values &amp; Units [[!CSS-VALUES-3]].
	Combination with other CSS modules may expand the definitions of these value types.

	In addition to the property-specific values listed in their definitions,
	all properties defined in this specification
	also accept the <a>CSS-wide keywords</a> as their property value.
	For readability they have not been repeated explicitly.

<h2 id='contain-property'>
Strong Containment: the 'contain' property</h2>

	Issue: [[css-contain-2#contain-property]]

	<pre class='propdef partial'>
		Name: contain
		New Values: layout || style || paint || [ size | [ inline-size || block-size ]]
	</pre>

	<dl dfn-type=value dfn-for=contain>
		<dt><dfn>inline-size</dfn>
		<dd>
			The value turns on <a>inline-size containment</a> for the element.
			This ensures that the inline [=size containment box|containment box=] can be laid out
			without needing to examine its descendants.
		<dt><dfn>block-size</dfn>
		<dd>
			The value turns on <a>block-size containment</a> for the element.
			This ensures that the block [=size containment box|containment box=] can be laid out
			without needing to examine its descendants.
	</dl>


<h2 id='containment-types'>
Types of Containment</h2>

	Issue: [[css-contain-2#containment-types]]

<h3 id='containment-inline-size'>
Inline-Size Containment</h3>

	Giving an element <dfn export>inline-size containment</dfn>
	makes its [=principal box=] behave as a [=size containment box=]
	on the [=inline axis=].

	Issue(1031): Define inline-size containment in more detail


<h3 id='containment-block-size'>
Block-Size Containment</h3>

	Giving an element <dfn export>block-size containment</dfn>
	makes its [=principal box=] behave as a [=size containment box=]
	on the [=block axis=].

	Issue(1031): Define block-size containment in more detail


<h2 id="container-queries">
Container Queries</h2>

	While [=media queries=] provide a method to query
	aspects of the user agent or device environment
	that a document is being displayed in
	(such as viewport dimensions or user preferences),
	[=container queries=] allow testing aspects of elements within the document
	(such as box dimensions or computed styles).

	A [=query container=] is established by specifying
	the possible query types using the 'container-type' property
	(or the 'container' [=shorthand=]).
	Style rules applying to its descendants can then be conditioned
	by querying against it,
	using the ''@container'' [=conditional group rule=].

	<div class=example>
		For example, we can define the main content area and sidebar as containers,
		and then describe a ''.media-object'' that changes
		from vertical to horizontal layout depending on the size of its container:

		<pre class=lang-css>
		main, aside {
		  container: inline-size;
		}

		.media-object {
		  display: grid;
		  grid-template: 'img' auto 'content' auto / 100%;
		}

		@container (inline-size > 45em) {
		  .media-object {
		    grid-template: 'img content' auto / auto 1fr;
		  }
		}
		</pre>

		Media objects in the main and sidebar areas
		will each respond to their own container context.
	</div>

<h3 id="container-type">
Creating Query Containers: the 'container-type' property</h2>

	<pre class='propdef'>
		Name: container-type
		Value: none | style || state || [ size | [ inline-size || block-size ]]
		Initial: none
		Inherited: no
		Applies to: all elements
		Computed value: the keyword ''container-type/none'' or one or more of ''container-type/size'', ''container-type/inline-size'', ''container-type/block-size'', ''container-type/style'', ''container-type/state''
		Animation type: not animatable
	</pre>

	The 'container-type' property establishes the element
	as a <dfn export>query container</dfn> for the purpose of [=container queries=],
	allowing [=style rules=] styling its descendants
	to query various aspects of its sizing, layout, and style
	and respond accordingly.

	Issue(6376): Bikeshed terms/property names to avoid confusion
	with other usage of “contain” and “container”?

	Values have the following meanings:

	<dl dfn-type=value dfn-for=container-type>
		<dt><dfn>size</dfn>
		<dd>
			Establishes a [=query container=] for [=dimensional queries=]
			on both the [=inline axis|inline=] and [=block axis=].
			Applies [=layout containment=],
			[=style containment=],
			and [=size containment=]
			to the [=principal box=].
		<dt><dfn>inline-size</dfn>
		<dd>
			Establishes a [=query container=] for [=dimensional queries=]
			on the container’s own [=inline axis=].
			Applies [=layout containment=],
			[=style containment=],
			and [=inline-size containment=]
			to the [=principal box=].
		<dt><dfn>block-size</dfn>
		<dd>
			Establishes a [=query container=] for [=dimensional queries=]
			on the container’s own [=block axis=].
			Applies [=layout containment=],
			[=style containment=],
			and [=block-size containment=]
			to the [=principal box=].
		<dt><dfn>style</dfn>
		<dd>
			Establishes a [=query container=] for [=style queries=].
		<dt><dfn>state</dfn>
		<dd>
			Establishes a [=query container=] for [=state queries=].
	</dl>

	<div class=example>
		For example, authors can create container-responsive typography,
		adjusting 'font-size', 'line-height', and other typographic concerns
		based on the size of a container:

		<pre class=lang-css>
		aside, main {
		  container-type: inline-size;
		}

		h2 { font-size: 1.2em; }

		@container (width > 40em) {
		  h2 { font-size: 1.5em; }
		}
		</pre>

		The ''40em'' value used in the query condition
		is relative to the [=computed value=] of 'font-size'
		on the ''section'' container.
	</div>

	<div class=example>
		Containers can also expose computed style values for querying.
		This can be useful for toggling behavior across multiple properties:

		<pre class=lang-css>
		section {
		  container-type: style;
		}

		@container (--cards) {
		  article {
		    border: thin solid silver;
		    border-radius: 0.5em;
		    padding: 1em;
		  }
		}
		</pre>
	</div>


<h3 id="container-name">
Naming Query Containers: the 'container-name' property</h2>

	<pre class='propdef'>
		Name: container-name
		Value: none | [ <<custom-ident>> | <<string>> ]+
		Initial: none
		Inherited: no
		Applies to: all elements
		Computed Value: a set of unique [=identifiers=]
		Animation type: not animatable
	</pre>

	The 'container-name' property
	specifies a list of <dfn export lt="query container name">query container names</dfn>.
	These names can be used by ''@container'' rules
	to filter which [=query containers=] are targeted.

	<dl dfn-for=container-name dfn-type=value>
	<dt><dfn>none</dfn>
	<dd>
		The [=query container=] has no [=query container name=].
	<dt><dfn><<custom-ident>></dfn>
	<dd>
		Specifies a [=query container name=] as an [=identifier=].
	<dt><dfn><<string>></dfn>
	<dd>
		Specifies a [=query container name=] as a <<string>> value;
		this computes to an [=identifier=]
		with the same value as the given <<string>>.
	</dl>

	The keyword <css>none</css> and the string "none"
	are invalid as <<custom-ident>> or <<string>> values.

	<div class=example>
		In some cases, we want to query aspects of a specific container,
		even if it's not the nearest ancestor container.
		For example, we might want to query the height of a main content area,
		and the width of a more nested inline-container.

		<pre class=lang-css>
		main {
		  container-type: size;
		  container-name: layout;
		}

		.grid-item {
		  container-type: inline-size;
		  container-name: component;
		}

		@container layout (block-size > 12em) {
		  .card { margin-block: 2em; }
		}

		@container component (inline-size > 30em) {
		  .card { margin-inline: 2em; }
		}
		</pre>
	</div>

	<div class=example>
		Since <<string>> values are allowed,
		we can also generate container names from attributes:

		<pre class=lang-css>
		[data-container] {
		  container-name: attr(data-container);
		}
		</pre>

		This will set the the [=query container name=]
		to use the contents of the ''data-container'' attribute when provided.
	</div>


<h3 id="container-shorthand">
Creating Named Containers: the 'container' shorthand</h2>

	<pre class='propdef shorthand'>
		Name: container
		Value: <<'container-type'>> [ / <<'container-name'>> ]?
	</pre>

	The 'container' [=shorthand property=] sets
	both 'container-type' and 'container-name' in the same declaration.
	If <<'container-name'>> is omitted,
	it is reset to its [=initial value=].

	<div class=example>
		We can define both a 'container-type' and 'container-name'
		using the shorthand syntax:

		<pre class=lang-css>
		main {
		  container: size / layout;
		}

		.grid-item {
		  container: inline-size / component;
		}
		</pre>
	</div>


<h3 id="container-rule">
Container Queries: the ''@container'' rule</h2>

	The <dfn at-rule id="at-ruledef-container">@container</dfn> rule
	is a [=conditional group rule=] whose condition is a [=container query=].

	The syntax of the ''@container'' rule is:

	<pre class="prod def">
	@container <<container-name>>? <<container-query-list>> {
	  <<stylesheet>>
	}
	</pre>

	The <dfn>&lt;container-query-list></dfn> represents the <dfn export>container query</dfn>
	and has the same syntax, parsing, and boolean interpretation as
	<<media-condition>> in [[MEDIAQUERIES-4]],
	but with [=container features=] instead of [=media features=].

	Styles in the <<stylesheet>> block of the ''@container'' rule
	are [[css-cascade-4#filtering|filtered]] by its condition
	to only match when the [=container query=]
	is true for the element’s [=query container=].

	For each element,
	the [=query container=] to be queried
	is determined by the following container selection process:

	1. Start with a list of all the element's ancestor [=query containers=].
	2. The optional <dfn><<container-name>></dfn>
		filters the set of [=query containers=] considered
		to just those with a matching [=query container name=].
	3. Select the nearest remaining [=query container=] ancestor.
	4. If no ancestor is an eligible [=query container=],
		then the [=container query=] is ''false'' for that element.

	If an eligible [=query container=] has been selected,
	each [=container feature=] in the <<container-query-list>>
	is evaluated against that [=query container=].
	If the selected [=query container=]
	is not a valid 'container-type' for the feature,
	then the [=container query=] is ''unknown'' for that element.

	<div class=example>
		As with [=media queries=],
		we can string together multiple conditions in a single query list:

		<pre class=lang-css>
		@container card (inline-size > 30em) and (--responsive = true) {
		  /* styles */
		}
		</pre>

		The styles above will only be applied
		if there nearest ancestor container named "card"
		meets both the '@container/inline-size' and [=style queries|style=] conditions.
	</div>

	Issue(6393): Provide a syntax to query a specific container-type?


<h2 id="container-features">
Container Features</h2>

	A <dfn export>container feature</dfn>
	queries a specific aspect of a [=query container=].
	Its syntax is the same as for a [=media feature=]:
	a feature name, a comparator, and a value, all wrapped in parentheses.
	[[mediaqueries-5]]

	Issue(5989): What container features can be queried?

<h3 id="dimensional-container">
Dimensional Container Features</h3>

	<dfn export>Dimensional queries</dfn> allow querying
	the size of the [=query container=]'s [=principal box=].

	If the [=query container=] does not have a [=principal box=],
	or the principal box is not a [=layout containment box=],
	then the result of evaluating any dimensional container feature is ''unknown''.

	[=Relative length=] units in [=container queries=]
	are based on the the [=computed values=] of the [=query container=].

	Note: This is different from the handling of relative units in [=media queries=].

	Issue: Evaluate to "unknown" if inline-/block-/size containment is missing.

<h4 id="width">
Width: the '@container/width' feature</h4>

	<pre class="descdef mq">
		Name: width
		For: @container
		Value: <<length>>
		Type: range
	</pre>

	The '@container/width' [=container feature=]
	queries the [=width=]
	of the [=query container=]’s [=content box=].

<h4 id="height">
Height: the '@container/height' feature</h4>

	<pre class="descdef mq">
		Name: height
		For: @container
		Value: <<length>>
		Type: range
	</pre>

	The '@container/height' [=container feature=]
	queries the [=height=]
	of the [=query container=]’s [=content box=].

<h4 id="inline-size">
Inline-size: the '@container/inline-size' feature</h4>

	<pre class="descdef mq">
		Name: inline-size
		For: @container
		Value: <<length>>
		Type: range
	</pre>

	The '@container/inline-size' [=container feature=]
	queries the [=size=]
	of the [=query container=]’s [=content box=]
	in the [=query container=]’s [=inline axis=].


<h4 id="block-size">
Block-size: the '@container/block-size' feature</h4>

	<pre class="descdef mq">
		Name: block-size
		For: @container
		Value: <<length>>
		Type: range
	</pre>

	The '@container/block-size' [=container feature=]
	queries the [=size=]
	of the [=query container=]’s [=content box=]
	in the [=query container=]’s [=block axis=].


<h4 id="aspect-ratio">
Aspect-ratio: the '@container/aspect-ratio' feature</h4>

	<pre class="descdef mq">
		Name: aspect-ratio
		For: @container
		Value: <<ratio>>
		Type: range
	</pre>

	The '@container/aspect-ratio' [=container feature=] is defined as the ratio
	of the value of the '@container/width' [=container feature=]
	to the value of the '@container/height' [=container feature=].


<h4 id="orientation">
Orientation: the '@container/orientation' feature</h4>

	<pre class="descdef mq">
		Name: orientation
		For: @container
		Value: portrait | landscape
		Type: discrete
	</pre>

	<dl dfn-type=value dfn-for="@container/orientation">
		<dt><dfn>portrait</dfn>
		<dd>
			The 'orientation' [=container feature=] is ''portrait''
			when the value of the '@container/height' [=container feature=]
			is greater than or equal to
			the value of the '@container/width' [=container feature=].
		<dt><dfn>landscape</dfn>
		<dd>Otherwise 'orientation' is ''landscape''.
	</dl>


<h3 id="style-container">
Style Container Features</h3>

	<dfn export>Style queries</dfn> allow querying
	the [=computed values=] of the [=query container=].

	Issue(6396): Define a syntax for style-based container queries

<h3 id="state-container">
State Container Features</h3>

	<dfn export>State queries</dfn> allow querying
	miscellaneous [=query container=] states, such as
	whether a ''position: sticky'' box is displaced from its in-flow position,
	or whether the box is visible on screen.

Issue: Define a syntax for state-based container queries

<h2 id="container-lengths">
Container Relative Lengths: the ''qw'', ''qh'', ''qi'', ''qb'', ''qmin'', ''qmax'' units</h2>

	<dfn lt="container length">Container length units</dfn>
	specify a length relative to another length.
	Style sheets that use relative units can more easily move components
	from one [=query container=] to another.

	The [=container length=] units are:

	<table class="data">
	<caption>Informative Summary of Container Units</caption>
	<thead>
		<tr><th>unit<th>relative to
	</thead>
	<tbody>
		<tr><td>''qw''
			<td>1% of a [=query container=]'s [=width=]
		<tr><td>''qh''
			<td>1% of a [=query container=]'s [=height=]
		<tr><td>''qi''
			<td>1% of a [=query container=]'s [=inline size=]
		<tr><td>''qb''
			<td>1% of a [=query container=]'s [=block size=]
		<tr><td>''qmin''
			<td>The smaller value of ''qi'' or ''qb''
		<tr><td>''qmax''
			<td>The larger value of ''qi'' or ''qb''
	</tbody>
	</table>

	For each element,
	[=container length=] units are evaluated
	as [=dimensional queries=] on the relevant axis or axes
	described by the unit.
	The [=query container=] for each axis
	is the nearest ancestor container
	that accepts [=dimensional queries=] on that axis.
	If no eligible [=query container=] is defined on the required axis,
	then the [=container length=] on that axis is zero (''0'').

	Note: In some cases ''qi'' and ''qb'' units on the same element
	will evaluate in relation to different [=query containers=].
	Similarly, ''qmin'' and ''qmax'' units represent
	the larger or smaller of the ''qi'' and ''qb'' units,
	even when those dimensions come from different [=query containers=].

	Child elements do not inherit the relative values as specified for their parent;
	they inherit the <a>computed values</a>.

	<div class=example>
		Since container relative units rely on being inside a proper container,
		and fallback to ''0'',
		it's often useful to establish a minimum value using math functions
		like ''calc()'', ''min()'', ''max()'', or ''clamp()'':

		<pre class=lang-css>
		article {
		  /* calc(1em + 0) = 1em */
		  font-size: calc(1em + 0.2qmin);

		  /* clamp(1em, 0, 3em) = 1em */
		  font-size: clamp(1em, 5qw, 3em);

		  /* clamp(1em, max(0, 3vw), 3em) = clamp(1em, 3vw, 3em) */
		  font-size: clamp(1em, max(5qw, 3vw), 3em);

		  /* max(0, 1em) max(0, 1em) = 1em 1em */
		  padding: max(2qh, 1em) max(2qw, 1em);
		}
		</pre>
	</div>

	Issue(5888): "container width" and "container height" units


Suppressing An Element's Contents Entirely: the 'content-visibility' property {#content-visibility}
=================

	Issue: [[css-contain-2#content-visibility]]

Privacy and Security Considerations {#priv-sec}
==============================================

	Issue: [[css-contain-2#priv-sec]]

<!--
████████ ████████  ██████
██          ██    ██    ██
██          ██    ██
██████      ██    ██
██          ██    ██
██          ██    ██    ██
████████    ██     ██████
-->

<h2 class="no-num non-normative" id="changes">Appendix A. Changes</h2>

This appendix is <em>informative</em>.

<h3 id="l3-changes">
Changes from <a href="https://www.w3.org/TR/css-contain-2/">CSS Containment Level 2</a>
</h3>

	* Defines the terms, properties, units, and at-rule
		needed for [=Container Queries=]

ISSUE: [[css-contain-2#changes]]

<h2 class="no-num" id="acknowledgments">Acknowledgments</h2>

	Comments and previous work from
	Adam Argyle,
	Amelia Bellamy-Royds,
	Anders Hartvoll Ruud,
	Brian Kardell,
	Chris Coyier,
	Christopher Kirk-Nielsen,
	David Herron,
	Elika J. Etemad (fantasai),
	Eric Portis,
	Ethan Marcotte,
	Geoff Graham,
	Gregory Wild-Smith,
	Ian Kilpatrick,
	Jen Simmons,
	Kenneth Rohde Christiansen,
	L. David Baron,
	Lea Verou,
	Martin Auswöger,
	Martine Dowden,
	Mike Riethmuller,
	Morten Stenshorne,
	Nicole Sullivan,
	Rune Lillesveen,
	Scott Jehl
	Scott Kellum,
	Stacy Kvernmo,
	Theresa O’Connor,
	Una Kravets,
	and many others have contributed to this specification.