Overview.bs

<pre class="metadata">
Title: CSS Conditional Rules Module Level 5
Group: csswg
Shortname: css-conditional
Level: 5
Status: ED
Prepare for TR: no
!Delta Spec: yes
Work Status: Exploring
ED: https://drafts.csswg.org/css-conditional-5/
TR: https://www.w3.org/TR/css-conditional-5/
Editor: L. David Baron, Mozilla https://www.mozilla.org/, https://dbaron.org/, w3cid 15393
Editor: Elika J. Etemad / fantasai, Apple, http://fantasai.inkedblade.net/contact, w3cid 35400
Editor: Chris Lilley, W3C, https://svgees.us/, w3cid 1438
Editor: Miriam E. Suzanne, Invited Expert, https://www.miriamsuzanne.com/who/, w3cid 117151
Abstract: This module contains the features of CSS
	for conditional processing of parts of style sheets,
	based on capabilities of the processor or the environment
	the style sheet is being applied in.
	It includes and extends the functionality of CSS Conditional 4 [[!css-conditional-4]],
	adding the generalized conditional rule ''@when''
	and the chained conditional rule ''@else'',
	as well as introducing font processing queries
	to the [=supports query=] syntax used in ''@supports'' rules,
	and container queries.
Default Highlight: css
</pre>

<pre class="link-defaults">
	spec: css-conditional-3
		type: dfn; text: conditional group rule
	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-pseudo-4; type:dfn; text:fictional tag sequence
	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:property;
		text:min-width
		text:min-height
	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-values-4; type:dfn; text:relative length
	spec:css-values-4; type:dfn; text:identifier
	spec:web-animations-1; type:dfn; text:effect values
	spec:css-cascade-5; type:dfn; text:property
</pre>

<h2 id="introduction">
Introduction</h2>

	ISSUE: This is currently an early draft of the things that are <em>new</em> in level 5.
	The features in Level 3 and Level 4 are still defined
	in [[css-conditional-3]] and [[css-conditional-4]]
	and have not yet been copied here.

	CSS Conditional Level 5 extends
	the ''@supports'' rule and [=supports query=] syntax
	to allow testing for supported font technologies.

	It also adds an ''@when'' rule,
	which generalizes the concept of a conditional rule.
	Anything that can be expressed in an existing conditional rule
	can be expressed in ''@when''
	by wrapping it in an appropriate function
	to declare what kind of condition it is.
	This allow authors to easily combine multiple types of queries,
	such as media queries and supports queries,
	in a single boolean expression.
	Without this,
	authors must rely on nesting separate conditional rules,
	which is harder to read and write,
	presupposes the conditions are to be conjoined with the “and” boolean relation
	(with no easy way to indicate anything else),
	and restricts their utility in the proposed [=conditional rule chains=].

	It also adds ''@else'' rules,
	which immediately follow other conditional rules
	and automatically qualify their conditions
	as the inverse of the immediately preceding rule’s conditions,
	such that only the first matching rule in a [=conditional rule chain=]
	is applied.

	It also adds Container Queries.
	They are conceptually similar to Media Queries,
	but allow testing aspects of elements within the document (such as box dimensions or computed styles),
	rather than on the document as a whole.

<h2 id="at-supports-ext">
Extensions to the ''@supports'' rule</h2>

	This level of the specification extends the <<supports-feature>> syntax as follows:

	<pre class="prod def" nohighlight>
		<dfn>&lt;supports-feature></dfn> = <<supports-selector-fn>> | <<supports-font-tech-fn>>
		                    | <<supports-font-format-fn>> | <<supports-decl>>
		<dfn>&lt;supports-font-tech-fn></dfn> = font-tech( <<font-tech>> )
		<dfn>&lt;supports-font-format-fn></dfn> = font-format( <<font-format>> )
	</pre>

	: <<supports-font-tech-fn>>
	::
		The result is true if the UA
		<a href="#dfn-support-font-tech">supports the font tech</a>
		provided as an argument to the function.

	: <<supports-font-format-fn>>
	::
		The result is true if the UA
		<a href="#dfn-support-font-format">supports the font format</a>
		provided as an argument to the function.

<h3 id="support-definition-ext">
Extensions to the definition of support</h3>

	A CSS processor is considered to
	<dfn export for=CSS id="dfn-support-font-tech">support a font tech</dfn>
	when it is capable of utilizing the specified [[css-fonts-4#font-tech-definitions]]
	in layout and rendering.

	A CSS processor is considered to
	<dfn export for=CSS id="dfn-support-font-format">support a font format</dfn>
	when it is capable of utilizing the specified [[css-fonts-4#font-format-definitions]]
	in layout and rendering,
	and this format is not specified as a <<string>>.

<h2 id="when-rule">
Generalized Conditional Rules: the ''@when'' rule</h2>

	The <dfn>@when</dfn> at-rule is a [=conditional group rule=]
	that generalizes the individual [=conditional group rules=]
	such as ''@media'' and ''@supports''.
	It is defined as:

	<pre class=prod>
		@when <<boolean-condition>> {
		  <<rule-list>>
		}
	</pre>

	Where <<boolean-condition>> is a boolean algebra a la [[mediaqueries-4#mq-syntax]],
	but with ''media()'' and ''supports()'' functions as leaves.

	Issue: Define "boolean algebra, with X as leaves" in a generic way in Conditional,
	so all the conditional rules can reference it directly,
	rather than having to redefine boolean algebra on their own.

	The ''media()'' and ''supports()'' functions are defined as:

	<pre class=prod>
	<dfn>media()</dfn> = media( [ <<mf-plain>> | <<mf-boolean>> | <<mf-range>> ] )
	<dfn>supports()</dfn> = supports( <<declaration>> )
	</pre>

	A ''media()'' or ''supports()'' function is associated the boolean result
	that its contained condition is associated with.

<h2 id="else-rule">
Chained Conditionals: the ''@else'' rule</h2>

	Usually, [=conditional group rules=] are independent;
	each one has a separate condition
	evaluated without direct reference to any other rule,
	and decides whether or not to apply its contained rules
	based solely on its condition.

	This is fine for simple conditions,
	but makes it difficult to write a collection of conditionals
	that are meant to be mutually exclusive:
	authors have to very carefully craft their conditions
	to not activate when the other rules are meant to,
	and make sure the collection of conditionals
	don't accidentally <em>all</em> exclude some situation
	which is then left unstyled.

	The <dfn>@else</dfn> rule is a [=conditional group rule=]
	used to form [=conditional rule chains=],
	which associate multiple [=conditional rules=]
	and guarantee that only the first one that matches
	will evaluate its condition as true.
	It is defined as:

	<pre class=prod>
		@else <<boolean-condition>>? {
			<<rule-list>>
		}
	</pre>

	''@else'' is interpreted identically to ''@when''.
	If its <<boolean-condition>> is omitted,
	it's treated as having a condition that's always true.

	A <dfn export>conditional rule chain</dfn> is
	a series of consecutive [=conditional group rules=],
	starting with a [=conditional group rule=] other than ''@else'',
	followed by zero or more ''@else'' rules.
	There cannot be anything between the successive [=conditional group rules=]
	other than whitespace and/or comments;
	any other token “breaks” the chain.

	Issue: Should we require that only the last ''@else'' in a chain can have an omitted condition?
	It's not uncommon for me, when debugging code,
	to short-circuit an if-else chain by setting one of them to "true";
	I presume that would be similarly useful in CSS?
	It's still pretty easy to see you've done something wrong if you omit the condition accidentally.

	Within a [=conditional rule chain=],
	the conditions of each [=conditional group rule=] are evaluated in order.
	If one of them is true,
	the conditions of all <em>following</em> [=conditional group rules=] in the chain
	evaluate to false,
	regardless of their stated condition.

	An ''@else'' rule that is not part of a [=conditional rule chain=]
	is invalid and must be ignored.

	<div class=example>
		For example, here's a (somewhat silly) conditional chain:

		<pre class="lang-css">
			@when media(width >= 400px) and media(pointer: fine) and supports(display: flex) {
			  /* A */
			} @else supports(caret-color: pink) and supports(background: double-rainbow()) {
			  /* B */
			} @else {
			  /* C */
			}
		</pre>

		Exactly one of the preceding rules will be chosen,
		even though the second rule
		doesn't exclude large widths, fine points, or flexbox support,
		and the last rule
		doesn't specify anything at all.

		To achieve the same result without [=conditional rule chains=],
		you'd need to write:

		<pre class="lang-css">
			@media (width >= 400px) and (pointer: fine) {
			  @supports (display: flex) {
			    /* A */
			  }
			  @supports not (display: flex) {
			    @supports (caret-color: pink) and (background: double-rainbow()) {
			      /* B */
			    }
			    @supports not ((caret-color: pink) and (background: double-rainbow())) {
			      /* C */
			    }
			  }
			}
			@media not ((width >= 400px) and (pointer: fine)) {
			  @supports (caret-color: pink) and (background: double-rainbow()) {
			    /* B */
			  }
			  @supports not ((caret-color: pink) and (background: double-rainbow())) {
			    /* C */
			  }
			}
		</pre>

		This is simultaneously hard to read,
		requires significant duplication of both conditions and contents,
		and is <em>very</em> difficult to write correctly.
		<!-- (I wrote it wrong <em>twice</em> while producing this example.) -->
		If the conditions got any more complicated
		(which is not unusual in real-world content),
		the example would get <em>significantly</em> worse.
	</div>

	<div class="example">
		In this example, three different color font technologies
		are tested, in order of preference,
		plus a monochrome fallback.
		The most capable, COLRv1, supports both gradients and font variations;
		the next best choice, SVG, supports gradients
		while the least capable, COLRv0, supports flat color fill only.

		The fallback has no test condition,
		so will always be chosen unless one of the earlier conditions succeeds.

		<pre class="lang-css">
			@when font-tech(color-COLRv1) and font-tech(variations) {
			  @font-face { font-family: icons; src: url(icons-gradient-var.woff2); }
			}
			@else font-tech(color-SVG) {
			  @font-face { font-family: icons; src: url(icons-gradient.woff2); }
			}
			@else font-tech(color-COLRv0) {
			  @font-face { font-family: icons; src: url(icons-flat.woff2); }
			}
			@else {
			  @font-face { font-family: icons; src: url(icons-fallback.woff2); }
			}
		</pre>

		Notice that in this example,
		the variable color font is only downloaded
		if COLRv1 is supported
		and font variations are also supported.

		Notice too that only one of the available options will be downloaded;
		this would not be the case without ''@when'' and ''@else'',
		as the next example shows.
	</div>

	<div class="example">
		In this example,
		although it appears that the fallback will not be used
		if COLRv1 is supported,
		in fact both fonts will be downloaded,
		which wastes bandwidth if it is not used.

		The fallback might still be used for some characters;
		for example, if the color font supports only Latin,
		while the fallback supports Latin and Greek.

		<pre class="lang-css">
			@font-face { font-family: icons; src: url(icons-fallback.woff2);
			@supports font-tech(color-COLRv1) {
			  @font-face { font-family: icons; src: url(icons-gradient-var.woff2); }
			}
		</pre>
	</div>

<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).

	By default, all elements are [=query containers=]
	for the purpose of [=container style queries=],
	and can be established as [=query containers=]
	for [=container size queries=] by specifying
	the additional query types using the 'container-type' property
	(or the 'container' [=shorthand=]).
	Style rules applying to a [=query container=]’s [=flat tree=] descendants
	can 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: my-layout / inline-size;
		}

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

		@container my-layout (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>

	For the ''::part()'' and ''::slotted()'' <a>pseudo-element</a> selectors,
	which represent real elements in the DOM tree, query containers can be
	established by [=flat tree=] ancestors of those elements.
	For other <a>pseudo-element</a>s, query containers can be established by
	inclusive [=flat tree=] ancestors of their <a>originating element</a>.

	<div class=note>
		It follows that:

		* ''::before'', ''::after'', ''::marker'', and ''::backdrop'' query their
			originating elements
		* ''::first-letter'' and ''::first-line'' query their originating elements,
			even if the <a>fictional tag sequence</a> may push the
			<code>::first-line</code> past other elements for the purpose of
			inheritance and rendering
		* ''::slotted()'' selectors can query containers inside the shadow tree,
			including the slot itself
		* ''::slotted()::before'' selectors can query the slotted shadow host child
		* ''::part()'' selectors can query containers inside the shadow tree
		* ''::placeholder'' and ''::file-selector-button'' can query the input
			element, but do not expose any internal containers if the input element is
			implemented using a shadow tree
	</div>

	<div class=example>
		A ::before selector querying the size of the originating element:

		<pre class=lang-html>
		&lt;style>
		  #container {
		    width: 100px;
		    container-type: inline-size;
		  }
		  @container (inline-size < 150px) {
		    #inner::before {
		      content: "BEFORE";
		    }
		  }
		&lt;/style>
		&lt;div id=container>
		  &lt;span id=inner>&lt;/span>
		&lt;/div>
		</pre>
	</div>

	<div class=example>
		A ::slotted() selector for styling a shadow host child can query a
		container in the shadow tree:

		<pre class=lang-html>
		&lt;div id=host style="width:200px">
		  &lt;template shadowroot=open>
		    &lt;style>
		      #container {
		        width: 100px;
		        container-type: inline-size;
		      }
		      @container (inline-size < 150px) {
		        ::slotted(span) {
		          color: green;
		        }
		      }
		    &lt;/style>
		    &lt;div id=container>
		      &lt;slot />
		    &lt;/div>
		  &lt;/template>
		  &lt;span id=slotted>Green&lt;/span>
		&lt;/div>
		</pre>
	</div>

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

	<pre class='propdef'>
		Name: container-type
		Value: normal | size | inline-size
		Initial: normal
		Inherited: no
		Applies to: all elements
		Computed value: specified keyword
		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=] that require explicit containment
	(such as [=container size queries=]),
	allowing [=style rules=] styling its descendants
	to query various aspects of its sizing and layout,
	and respond accordingly.

	Unless otherwise noted,
	all elements are [=query containers=]
	for the purpose of [=container queries=]
	that do not require explicit [=containment=]
	(such as [=container style queries=]),
	regardless of the specified 'container-type'.

	Values have the following meanings:

	<dl dfn-type=value dfn-for=container-type>
		<dt><dfn>size</dfn>
		<dd>
			Establishes a [=query container=] for [=container size 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 [=container size queries=]
			on the container’s own [=inline axis=].
			Applies [=layout containment=],
			[=style containment=],
			and [=inline-size containment=]
			to the [=principal box=].
		<dt><dfn>normal</dfn>
		<dd>
			The element is not a [=query container=]
			for any [=container size queries=],
			but remains a [=query container=] for [=container style 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 relevant [=query 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>
		@container style(--cards: small) {
		  article {
		    border: thin solid silver;
		    border-radius: 0.5em;
		    padding: 1em;
		  }
		}
		</pre>
	</div>


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

	<pre class='propdef'>
		Name: container-name
		Value: none | <<custom-ident>>+
		Initial: none
		Inherited: no
		Applies to: all elements
		Computed Value: the keyword ''container-name/none'', or an ordered list of [=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=].
		The keywords ''container-name/none'', ''and'', ''not'', and ''or'' are excluded from this <<custom-ident>>.
	</dl>

	<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: my-page-layout;
		}

		.my-component {
		  container-type: inline-size;
		  container-name: my-component-library;
		}

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

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


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

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

	The 'container' [=shorthand property=] sets
	both 'container-type' and 'container-name' in the same declaration.
	If <<'container-type'>> 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: my-layout / size;
		}

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


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

	The <dfn at-rule id="at-ruledef-container">@container</dfn> rule
	is a [=conditional group rule=] whose condition contains
	a <dfn export>container query</dfn>,
	which is a boolean combination of [=container size queries=] and/or [=container style queries=].
	Style declarations within the <<block-contents>> block of an ''@container'' rule
	are [[css-cascade-4#filtering|filtered]] by its condition
	to only match when the [=container query=]
	is true for their element’s [=query container=].

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

	<pre class="prod def">
	@container <<container-condition>># {
	  <<block-contents>>
	}
	</pre>

	where:

	<pre class="prod def">
	<dfn><<container-condition>></dfn> = [ <<container-name>> ]? <<container-query>>
	<dfn><<container-name>></dfn> = <<custom-ident>>
	<dfn><<container-query>></dfn>     = not <<query-in-parens>>
	                      | <<query-in-parens>> [ [ and <<query-in-parens>> ]* | [ or <<query-in-parens>> ]* ]
	<dfn><<query-in-parens>></dfn>     = ( <<container-query>> )
	                      | ( <<size-feature>> )
	                      | style( <<style-query>> )
	                      | <<general-enclosed>>

	<dfn><<style-query>></dfn>         = not <<style-in-parens>>
	                      | <<style-in-parens>> [ [ and <<style-in-parens>> ]* | [ or <<style-in-parens>> ]* ]
	                      | <<style-feature>>
	<dfn><<style-in-parens>></dfn>     = ( <<style-query>> )
	                      | ( <<style-feature>> )
	                      | <<general-enclosed>>
	</pre>

	The keywords ''container-name/none'', ''and'', ''not'', and ''or''
	are excluded from the <<custom-ident>> above.

	For each element,
	the [=query container=] to be queried
	is selected from among the element’s ancestor [=query containers=]
	that are established as a valid [=query container=]
	for all the [=container features=]
	in the <<container-query>>. If the <<container-query>> contains
	unknown or unsupported [=container feature=]s,
	no [=query container=] will be selected for that <<container-condition>>.
	The optional <<container-name>>
	filters the set of [=query containers=] considered
	to just those with a matching [=query container name=].

	Once an eligible [=query container=] has been selected for an element,
	each [=container feature=] in the <<container-query>>
	is evaluated against that [=query container=].
	If no ancestor is an eligible [=query container=],
	then the [=container query=] is ''unknown'' for that element.
	As with media queries, <<general-enclosed>> evaluates to ''unknown''.

	If a [=container query=] includes multiple <<container-condition>>s,
	each condition will select it's own [=query container=],
	and evaluate independently.
	A [=container query=] is ''true'' if <em>any</em> of its component
	<<container-condition>>s are ''true'',
	and ''false'' only if <em>all</em> of its component
	<<container-condition>>s are ''false''.

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

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

		The styles above will only be applied
		if there is an ancestor container named "card"
		that meets both the '@container/inline-size'
		and [=container style query|style=] conditions.

		We can also combine multiple conditions into a list,
		with each condition evaluating against a different container:

		<pre class=lang-css>
		@container card (inline-size > 30em), style(--large: true) {
		  /* styles */
		}
		</pre>

		The styles above will be applied
		if there is an ancestor container named "card"
		that meets the '@container/inline-size' condition
		<em>or</em> the nearest style container
		meets the [=container style query|style=] condition.
	</div>

	Style rules defined on an element inside multiple nested [=container queries=]
	apply when all of the wrapping [=container queries=] are true for that element.

	Note: Nested [=container queries=] can evaluate in relation to different containers,
	so it is not always possible to merge the individual <<container-condition>>s
	into a single query.

	<div class=example>
		Using a single comma-separated [=container query=],
		we can query multiple containers:

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

		The styles above will apply for an element inside <em>either</em>
		a container named "card" that meets the '@container/inline-size' condition,
		<em>or</em> a container meeting the [=container style query|style=] condition.

		In order to require that <em>all</em> conditions are met
		while querying multiple containers,
		we would need to nest multiple queries:

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

		The styles above will only be applied
		if there is <em>both</em> an ancestor container named "card"
		that meets the '@container/inline-size' condition,
		<em>and</em> an ancestor container
		meeting the [=container style query|style=] condition.
	</div>

	Global, name-defining [=at-rules=]
	such as ''@keyframes'' or ''@font-face'' or ''@layer''
	that are defined inside [=container queries=]
	are not constrained by the [=container query=] conditions.


<h3 id="animated-containers">
Animated Containers</h3>

	A change in the evaluation of a [=container query=] must be part of a [=style change event=],
	even when the change occurred because of [=effect values|animation effects=].

	<div class=example>
		A transition on a sibling element can indirectly affect the size of a
		container, triggering [=style change events=] whenever container queries
		change their evaluation as a result:

		<pre class=lang-css>
			main {
			  display: flex;
			  width: 300px;
			}

			#container {
			  container-type: inline-size;
			  flex: 1;
			}

			/* Resolved width is initially 200px, but changes as the transition
			   on #sibling progresses. */
			#inner {
			  transition: 1s background-color;
			  background-color: tomato;
			}

			/* When this container query starts (or stops) applying, a transition
			   must start on background-color on #inner. */
			@container (width <= 150px) {
			  #inner {
			    background-color: skyblue;
			  }
			}

			#sibling {
			  width: 100px;
			  transition: width 1s;
			}

			#sibling:hover {
			  width: 200px;
			}
		</pre>

		<pre class=lang-html>
			&lt;main>
			  &lt;div id=container>
			    &lt;div id=inner>Inner&lt;/div>
			  &lt;/div>
			  &lt;div id=sibling>Sibling&lt;/div>
			&lt;/main>
		</pre>

	</div>

	Changes in [=computed values=] caused by [=container query length=] units
	must also be part of a [=style change event=].


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

	A <dfn export>container feature</dfn>
	queries a specific aspect of a [=query container=].


<h3 id="size-container">
Size Container Features</h3>

	A <dfn export>container size query</dfn>
	allows querying
	the size of the [=query container=]’s [=principal box=].
	It is a boolean combination of
	individual <dfn>size features</dfn> (<<size-feature>>)
	that each query a single, specific dimensional feature of the [=query container=].
	The syntax of a <dfn><<size-feature>></dfn> is the same as for a [=media feature=]:
	a feature name, a comparator, and a value.
	[[mediaqueries-5]]
	The boolean syntax and logic combining [=size features=] into a [=container size query|size query=]
	is the same as for [=CSS feature queries=].
	(See ''@supports''. [[!css-conditional-3]])

	If the [=query container=] does not have a [=principal box=],
	or the principal box is not a [=layout containment box=],
	or the [=query container=] does not support [=container size queries=] on the relevant axes,
	then the result of evaluating the [=size feature=] is unknown.

	[=Relative length=] units
	(including [=container query length=] units)
	and [=custom properties=]
	in [=container query=] conditions
	are evaluated based on the [=computed values=] of the [=query container=].

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

	Note: If [=custom property=] substitution results in an invalid value for the
	[=size feature=], it is handled the same as other invalid feature values,
	and the result of the [=size feature=] is ''unknown''.

	<div class=example>
		For example, [=query containers=] with different font-sizes
		will evaluate ''em''-based queries relative to their own font sizes:

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

		aside { font-size: 16px; }
		main { font-size: 24px; }

		@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 relevant [=query container=]:

		* For any ''h2'' inside ''aside'',
			the query condition will be true above ''640px''.
		* For any ''h2'' inside ''main'',
			the query condition will be true above ''960px''.
	</div>

	<div class=example>
		Similarly, [=query containers=] will evaluate ''var()''-based queries
		relative to their own [=computed value=] of the [=custom property=]:

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

		aside { --query: 300px; }
		main { --query: 500px; }

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

		The ''var(--query)'' value used in the query condition
		is substituted with the [=computed value=] of
		the ''--query'' [=custom property=] on the relevant [=query container=]:

		* For any ''h2'' inside ''aside'',
			the query condition will be true above ''300px''.
		* For any ''h2'' inside ''main'',
			the query condition will be true above ''500px''.
	</div>

<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 '@container/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 '@container/orientation' is ''landscape''.
	</dl>


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

	A <dfn export>container style query</dfn>
	allows querying
	the [=computed values=] of the [=query container=].
	It is a boolean combination of
	individual <dfn>style features</dfn> (<<style-feature>>)
	that each query a single, specific property of the [=query container=].
	The syntax of a <dfn><<style-feature>></dfn> is either the same as for a valid [=declaration=]
	[[!CSS-SYNTAX-3]], a [=supported CSS property=], or a <<custom-property-name>>.

	Its query evaluates to true if the [=computed value=] of the given property on the
	[=query container=] matches the given value (which is also [=computed value|computed=]
	with respect to the [=query container=]), and false otherwise.

	A [=style feature=] without a value evaluates to true if the [=computed value=]
	is different from the [=initial value=] for the given [=property=].

	The boolean syntax and logic combining [=style features=] into a [=container style query|style query=]
	is the same as for [=CSS feature queries=].
	(See ''@supports''. [[!css-conditional-3]])

	[=Style features=] that query a [=shorthand property=] are true if the
	[=computed values=] match for each of its [=longhand properties=],
	and false otherwise.

	[=Cascade-dependent keywords=], such as ''revert'' and ''revert-layer'',
	are invalid as values in a [=style feature=], and cause the
	[=container style query=] to be false.

	Note: The remaining non-cascade-dependent [=CSS-wide keywords=]
	are [=computed value|computed=] with respect to the [=query container=],
	the same as other values.

<h2 id="container-lengths">
Container Relative Lengths: the ''cqw'', ''cqh'', ''cqi'', ''cqb'', ''cqmin'', ''cqmax'' units</h2>

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

	The [=container query length=] units are:

	<table class="data">
	<caption>Informative Summary of Container Units</caption>
	<thead>
		<tr><th>unit<th>relative to
	</thead>
	<tbody>
		<tr><td>''cqw''
			<td>1% of a [=query container=]’s [=width=]
		<tr><td>''cqh''
			<td>1% of a [=query container=]’s [=height=]
		<tr><td>''cqi''
			<td>1% of a [=query container=]’s [=inline size=]
		<tr><td>''cqb''
			<td>1% of a [=query container=]’s [=block size=]
		<tr><td>''cqmin''
			<td>The smaller value of ''cqi'' or ''cqb''
		<tr><td>''cqmax''
			<td>The larger value of ''cqi'' or ''cqb''
	</tbody>
	</table>

	For each element,
	[=container query length=] units are evaluated
	as [=container size queries=] on the relevant axis (or axes)
	described by the unit.
	The [=query container=] for each axis
	is the nearest ancestor container
	that accepts [=container size queries=] on that axis.
	If no eligible [=query container=] is available,
	then use the [=small viewport size=] for that axis.

	Note: In some cases ''cqi'' and ''cqb'' units on the same element
	will evaluate in relation to different [=query containers=].
	Similarly, ''cqmin'' and ''cqmax'' units represent
	the larger or smaller of the ''cqi'' and ''cqb'' 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>
		Authors can ensure that [=container query length=] units
		have an appropriate [=query container=]
		by applying them inside a [=container query=]
		that relies on the same ''container-type''.
		Custom fallback values can be defined outside the [=container query=]:

		<pre class=lang-css>
		/* The fallback value does not rely on containment */
		h2 { font-size: 1.2em; }

		@container (inline-size >= 0px) {
		  /* only applies when an inline-size container is available */
		  h2 { font-size: calc(1.2em + 1cqi); }
		}
		</pre>
	</div>


<h2 id="apis">APIs</h2>


<h3 id="the-csscontainerrule-interface">
The <code>CSSContainerRule</code> interface</h3>

	The {{CSSContainerRule}} interface represents a ''@container'' rule.

	<pre class='idl'>
	[Exposed=Window]
	interface CSSContainerRule : CSSConditionRule {
	    readonly attribute CSSOMString containerName;
	    readonly attribute CSSOMString containerQuery;
	};
	</pre>

	<dl class='idl-attributes'>
		<dt><code>conditionText</code> of type <code>CSSOMString</code> (CSSContainerRule-specific definition for attribute on CSSConditionRule)
		<dd>The <code>conditionText</code> attribute (defined on the <code>CSSConditionRule</code> parent rule),
			on getting, must return a value as follows:

			<dl class="switch">
				<dt data-md>The ''@container'' rule has an associated <<container-name>>
				<dd data-md>The result of getting the <code>containerName</code> and
					<code>containerQuery</code> attributes, joined by a single whitespace.
				<dt data-md>Otherwise
				<dd data-md>The result of getting the <code>containerQuery</code> attribute.
			</dl>

		<dt><code>containerName</code> of type <code>CSSOMString</code>
		<dd>The <code>containerName</code> attribute, on getting, must return a value as follows:

			<dl class="switch">
				<dt data-md>The ''@container'' rule has an associated <<container-name>>
				<dd data-md>The result of serializing that <<container-name>>.
				<dt data-md>Otherwise
				<dd data-md>An empty string.
			</dl>

		<dt><code>containerQuery</code> of type <code>CSSOMString</code>
		<dd>The <code>containerQuery</code> attribute,
			on getting, must return the <<container-query>> that was specified,
			without any logical simplifications,
			so that the returned query will evaluate to the same result
			as the specified query
			in any conformant implementation of this specification
			(including implementations that implement future extensions
			allowed by the <<general-enclosed>> extensibility mechanism in this specification).
			In other words,
			token stream simplifications are allowed
			(such as reducing whitespace to a single space
			or omitting it in cases where it is known to be optional),
			but logical simplifications (such as removal of unneeded parentheses,
			or simplification based on evaluating results) are not allowed.
	</dl>

	Issue(6205): Container Queries should have a <code>matchContainer</code> method.
	This will be modeled on {{matchMedia()}} and the {{MediaQueryList}} interface,
	but applied to Elements rather than the Window.
	When measuring layout sizes, it behaves Similar to <code>resizeObserver</code>,
	but it provides the additional Container Query syntax and features.

<h2 class=no-num id="security">Security Considerations</h2>

	No security issues have been raised against this document

<h2 class=no-num id="privacy">Privacy Considerations</h2>

	<!-- COPY FROM L3 when importing the rest of the spec -->

	The ''font-tech()'' and ''font-format()'' functions
	may provide information about the user's software
	such as its version
	and whether it is running with non-default settings that enable or disable certain features.

	This information can also be determined through other APIs.
	However, the features in this specification are one of the ways this information
	is exposed on the Web.

	This information can also, in aggregate, be used to improve the accuracy of
	<a href="https://www.w3.org/2001/tag/doc/unsanctioned-tracking/">fingerprinting</a> of the user.



<h2 id='changes' class='no-num'>
Changes</h2>

<h3 id="changes-20240723"  class="no-num">
Changes since the <a href="https://www.w3.org/TR/2024/WD-css-conditional-5-20240723/">Working Draft of 23 July 2024</a>
</h3>

<ul>
	<!-- To 9 Aug 2024 -->
	<li>Corrected example (there is no container-type:style)</li>
	<li>Specified that container queries use the flat tree (<a href="https://github.com/w3c/csswg-drafts/issues/5984#issuecomment-2112977366">Issue 5984</a>) </li>
</ul>

<h3 id="changes-20211221"  class="no-num">
Changes since the <a href="https://www.w3.org/TR/2021/WD-css-conditional-5-20211221/">First Public Working Draft of 21 December 2021</a>
</h3>

	<ul>
		<!-- to 18 Jun 2024 -->
		<li>Moved container queries to this specification, from CSS Contain 3  (<a href="https://github.com/w3c/csswg-drafts/issues/10433">#10433</a>)</li>
		<li>Imported the definitions of &lt;font-format> and &lt;font-tech> from CSS Fonts 4, rather than duplicating them in this specification (<a href="https://github.com/w3c/csswg-drafts/issues/8110">#8110</a>)</li>
		<li> Updated to use the new parsing algorithm names and block production names</li>
		<li>Corrected a typo in the grammar of &lt;font-format></li>
		<li>Corrected extra spaces in the font-tech and font-format productions (<a href="https://github.com/w3c/csswg-drafts/issues/7369">#7369</a> )</li>
	</ul>

<h3 id="changes-from-L4" class="no-num">
Additions since Level 4</h3>

	<ul>
		<li>Added ''@when'' and ''@else''.
		<li>Extended [=supports queries=] to express font capabilities
			via ''font-tech()'' and ''font-format()''.
		<li>Moved Container Queries from [[CSS-CONTAIN-3] to this specification.
			(See also the [[CSS-CONTAIN-3#changes]] for more information
			on the evolution of this feature.)
	</ul>

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

	The ''@when'' and ''@else'' rules are based on a proposal by Tab Atkins.

	Comments and previous work from
	Adam Argyle,
	Amelia Bellamy-Royds,
	Anders Hartvoll Ruud,
	Brian Kardell,
	Chris Coyier,
	Christopher Kirk-Nielsen,
	David Herron,
	Eric Portis,
	Ethan Marcotte,
	Florian Rivoal,
	Geoff Graham,
	Gregory Wild-Smith,
	Ian Kilpatrick,
	Jen Simmons,
	Kenneth Rohde Christiansen,
	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.