Title: CSS Conditional Rules Module Level 5
Group: csswg
Shortname: css-conditional
Level: 5
Status: WD
Prepare for TR: yes
Date: 2025-10-30
!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, Google https://www.google.com/, 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
Editor: Lea Verou, Invited Expert, https://lea.verou.me/about, w3cid 52258
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
WPT Path Prefix: css/css-conditional/
WPT Display: open
ISSUE: This is currently an early draft of the things that are new 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 custom support conditions as well as supported [=at-rules=] and 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.
Extensions to the ''@supports'' rule
This level of the specification extends the <> syntax as follows:
<declaration> here matches anything that would be successfully parsed by [=consume a declaration=],
ignoring the context-validation check at the end of that algorithm.
Notably, this includes a trailing ''!important'',
which is valid but ignored for the purpose of ''@supports''.
: <>
::
The result is true if the UA
supports the named condition.
If the name is not recognized,
the result is false.
: font-tech( <> )
::
The result is true if the UA
[=supports the font tech=]
provided as an argument to the function.
: font-format( <> )
::
The result is true if the UA
[=supports the font format=]
provided as an argument to the function.
: at-rule( <> )
::
The result is true if the UA
[=supports the at-rule=]
provided as an argument to the function.
: named-feature( <> )
::
The result is true if the UA
[=supports the named feature=]
provided as an argument to the function.
: env( <> )
::
The result is true if the UA
[=supports the environment variable=]
provided as an argument to the function.
Extensions to the definition of support
Font techs and formats
js/CSS-supports-L5.html
A CSS processor is considered to
support a font tech
when it is capable of utilizing the specified [[css-fonts-4#font-tech-definitions]]
in layout and rendering.
A CSS processor is considered to
support a font format
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 <>.
At-rules
js/supports-at-rule.html
A CSS processor is considered to
support an at-rule
if it would accept an [=at-rule=] beginning with the specified at-keyword
within any context.
Note: Because ''@charset'' is not a valid [=at-rule=],
it is not considered to be supported under this definition.
Named features
A CSS processor is considered to
support an named feature
if it supports the named feature based on the feature definition
described in the following list:
[ No features are currently defined. ]
If the feature is not listed the processor does not support the named feature.
Note: The CSS Working Group intends to add features to this list rarely,
when there is real demand for feature testing something specific
and it would be unreasonable to add a more general feature testing mechanism
that would cover the use case.
Named conditions
A CSS processor is considered to
support a named condition
when the related [=named supports condition=] returns true.
Environment variables
A CSS processor is considered to
support an environment variable
if the <> is a supported [=environment variable=].
Generalized Conditional Rules: the ''@when'' rule
The @when at-rule is a [=conditional group rule=]
that generalizes the individual [=conditional group rules=]
such as ''@media'' and ''@supports''.
It is defined as:
@when <> {
<>
}
Where <> 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:
A ''media()'' or ''supports()'' function is associated with the boolean result
that its contained condition is associated with.
Chained Conditionals: the ''@else'' rule
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 all exclude some situation
which is then left unstyled.
The @else rule is a [=conditional group rule=]
used to form [=conditional rule chains=],
which associate multiple [=conditional group rules=]
and guarantee that only the first one that matches
will evaluate its condition as true.
It is defined as:
@else <>? {
<>
}
''@else'' is interpreted identically to ''@when''.
If its <> is omitted,
it's treated as having a condition that's always true.
A conditional rule chain 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 following [=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.
For example, here's a (somewhat silly) conditional chain:
@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 */
}
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:
@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 */
}
}
This is simultaneously hard to read,
requires significant duplication of both conditions and contents,
and is very difficult to write correctly.
If the conditions got any more complicated
(which is not unusual in real-world content),
the example would get significantly worse.
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.
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.
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.
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=] and [=container scroll-state 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=].
An ancestor element that generates a box is not an eligible container for
[=container size queries=] if that box is not an ancestor box of any boxes
generated by the querying element.
There are cases where the box for a [=pseudo-element=] is generated as a
sibling box of its originating element's box. If we allowed querying the size
of a sibling box, it would introduce layout cycles.
For example, the ''::scroll-marker-group'' and ''::scroll-button()'' pseudo-elements
generate sibling boxes of their originating element's box.
These pseudo-elements will not be able to query their originating scroller
for [=container size queries=]. They will, however, be able to query other
eligible [=query container=] ancestors.
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:
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;
}
}
Media objects in the main and sidebar areas
will each respond to their own container context.
For the ''::part()'' and ''::slotted()'' pseudo-element selectors,
which represent real elements in the DOM tree, [=query containers=] can be
established by [=flat tree=] ancestors of those elements.
For other pseudo-elements, [=query containers=] can be established by
inclusive [=flat tree=] ancestors of their originating element.
It follows that:
* ''::before'', ''::after'', ''::marker'', and ''::backdrop'' query their
originating elements
* ''::first-letter'' and ''::first-line'' query their originating elements,
even if the fictional tag sequence may push the
::first-line 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
A ::before selector querying the size of the originating element:
Creating Query Containers: the 'container-type' property
Name: container-type
Value: normal | [ [ size | inline-size ] || scroll-state ]
Initial: normal
Inherited: no
Applies to: all elements
Computed value: specified keyword
Animation type: not animatable
The 'container-type' property establishes the element as a
[=query container=] for certain types of queries. For size
[=container queries=], which require certain types of containment, elements
are explicitly made [=query containers=] through this property. For other
types of [=query containers=] any element can be a [=query container=], such
as for [=container style queries=].
Values have the following meanings:
size
Establishes a [=query container=] for [=container size queries=]
on both the [=inline axis|inline=] and [=block axis=].
Applies [=style containment=] and [=size containment=]
to the [=principal box=],
and establishes an [=independent formatting context=].
inline-size
Establishes a [=query container=] for [=container size queries=]
on the container’s own [=inline axis=].
Applies [=style containment=] and [=inline-size containment=]
to the [=principal box=],
and establishes an [=independent formatting context=].
scroll-state
Establishes a [=query container=] for [=container scroll-state queries=]
normal
The element is not a [=query container=]
for any [=container size queries=] or [=container scroll-state queries=],
but remains a [=query container=] for [=container style queries=].
For example, authors can create container-responsive typography,
adjusting 'font-size', 'line-height', and other typographic concerns
based on the size of a container:
Containers can also expose state that depends on scroll offset. This example
styles a descendant of a sticky positioned element when it is stuck to the
top edge:
Naming Query Containers: the 'container-name' property
Name: container-name
Value: none | <>+
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
container-queries/container-ident-function.html
container-queries/container-ident-function.html
The 'container-name' property
specifies a list of query container names.
These names can be used by ''@container'' rules
to filter which [=query containers=] are targeted.
Container names are not [=tree-scoped names=].
none
The [=query container=] has no [=query container name=].
<>
Specifies a [=query container name=] as an [=identifier=].
The keywords ''container-name/none'', ''and'', ''not'', and ''or'' are excluded from this <>.
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.
The @container rule
is a [=conditional group rule=] whose condition contains
a container query,
which is a boolean combination of [=container size queries=] and/or [=container style queries=].
Style declarations within the ''@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:
container-queries/container-ident-function.html
container-queries/container-ident-function.html
container-queries/multiple-size-containers-comma-separated-queries.html
container-queries/multiple-style-containers-comma-separated-queries.html
container-queries/query-container-name.html
container-queries/scroll-state/at-container-scrolled-parsing.html
container-queries/scroll-state/multiple-scroll-state-containers-comma-separated-queries.html
container-queries/scroll-state/scroll-state-query-with-var.html
container-queries/size-query-with-var.html
The keywords ''container-name/none'', ''and'', ''not'', and ''or''
are excluded from the <> 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 <>. If the <> contains
unknown or unsupported [=container feature=]s,
no [=query container=] will be selected for that <>.
The <> 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 <>
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, <> evaluates to ''unknown''.
If the <> is omitted, the [=query container=] is eligible as
long as the <> matches.
If a [=container query=] includes multiple <>s,
each condition will select it's own [=query container=],
and evaluate independently.
A [=container query=] is ''true'' if any of its component
<>s are ''true'',
and ''false'' only if all of its component
<>s are ''false''.
As with [=media queries=],
we can string together multiple queries in a single condition:
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:
The styles above will be applied
if there is an ancestor container named "card"
that meets the '@container/inline-size' condition
or the nearest style container
meets the [=container style query|style=] condition.
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 <>s
into a single query.
Using a single comma-separated [=container query=],
we can query multiple containers:
The styles above will apply for an element inside either
a container named "card" that meets the '@container/inline-size' condition,
or a container meeting the [=container style query|style=] condition.
In order to require that all conditions are met
while querying multiple containers,
we would need to nest multiple queries:
The styles above will only be applied
if there is both an ancestor container named "card"
that meets the '@container/inline-size' condition,
and an ancestor container
meeting the [=container style query|style=] condition.
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.
Animated Containers
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=].
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:
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;
}
Changes in [=computed values=] caused by [=container query length=] units
must also be part of a [=style change event=].
Container Features
A container feature
queries a specific aspect of a [=query container=].
[=Container features=] use the same rules as [=media features=] when evaluating
in a [=boolean context=].
Size Container Features
A container size query
allows querying
the size of the [=query container=]’s [=principal box=].
It is a boolean combination of
individual size features (<>)
that each query a single, specific dimensional feature of the [=query container=].
The syntax of a <> 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]])
container-queries/size-container-auto-height.html
container-queries/var-evaluation.html
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=].
Tree counting functions ([[css-values-5#tree-counting]]) are evaluated against
the container element.
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''.
For example, [=query containers=] with different font-sizes
will evaluate ''em''-based queries relative to their own font sizes:
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''.
Similarly, [=query containers=] will evaluate ''var()''-based queries
relative to their own [=computed value=] of the [=custom property=]:
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''.
Width: the '@container/width' feature
Name: width
For: @container
Value: <>
Type: range
The '@container/width' [=container feature=]
queries the [=width=]
of the [=query container=]’s [=content box=].
Height: the '@container/height' feature
Name: height
For: @container
Value: <>
Type: range
The '@container/height' [=container feature=]
queries the [=height=]
of the [=query container=]’s [=content box=].
Inline-size: the '@container/inline-size' feature
Name: inline-size
For: @container
Value: <>
Type: range
The '@container/inline-size' [=container feature=]
queries the [=size=]
of the [=query container=]’s [=content box=]
in the [=query container=]’s [=inline axis=].
Block-size: the '@container/block-size' feature
Name: block-size
For: @container
Value: <>
Type: range
The '@container/block-size' [=container feature=]
queries the [=size=]
of the [=query container=]’s [=content box=]
in the [=query container=]’s [=block axis=].
Aspect-ratio: the '@container/aspect-ratio' feature
Name: aspect-ratio
For: @container
Value: <>
Type: range
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=].
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=].
landscape
Otherwise '@container/orientation' is ''landscape''.
Style Container Features
A container style query allows querying
the [=computed values=] of the [=query container=].
It is a boolean combination of individual style features
(<>) that each query a single, specific property of the [=query container=].
The syntax of a <>
is either the same as for a valid [=declaration=][[!CSS-SYNTAX-3]],
a <>
or a valid style range (<>).
The <> can be either a [=supported CSS property=]
or a valid <>.
The <> production matches any valid <>
as long as it doesn't contain <>, <> and <> tokens.
container-queries/style-query-registered-custom-rem-change.html
container-queries/style-query-unset-on-root.html
A <> 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=].
To evaluate a <>,
the following steps needs to be performed:
1. If <> is a <>,
it needs to be substituted
as if the <> was wrapped inside a ''var()''.
2. Substitute [=arbitrary substitution function=] within <>.
3. Parse <> to
<>, <>, <>, <>, <
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.
Scroll State Container Features
A container scroll-state query allows querying a container for
state that depends on scroll position. It is a boolean combination of
individual scroll-state features
(<>) that each query a single feature of the
[=query container=]. The syntax of a <> is the
same as for a [=media feature=]: a feature name, a comparator, and a value.
[=Scroll-state features=] can either match state of the scroller itself,
or an element that is affected by the scroll position of an ancestor
[=scroll container's=] [=scrollport=]. An example of the former is the
''scrollable'' feature, ''snapped'' the latter.
Updating Scroll State
Scroll state may cause layout cycles since queried scroll state may cause style changes,
which may lead to scroll state changes as a result of layout.
To avoid such layout cycles, ''scroll-state'' [=query containers=] update their
current state as part of [=run snapshot post-layout state steps=] which is only
run at specific points in the
HTML event loop processing model.
When asked to [=run snapshot post-layout state steps=], update the current state
of every ''scroll-state'' [=query container=]. This snapshotted state will be used
for any style and layout updates until the next time these steps are run.
Sticky positioning: the '@container/stuck' feature
Name: stuck
For: @container
Value: none | top | right | bottom | left | block-start | inline-start | block-end | inline-end
Type: discrete
container-queries/scroll-state/scroll-state-stuck-pseudo.html
The '@container/stuck' [=container feature=] queries whether a
''position/sticky'' positioned container is visually shifted to stay inside
the [=sticky view rectangle=] for the given edge. The logical edges map to
physical based on the direction and writing-mode of the [=query container=].
None of the values match if the [=query container=] is not [=sticky positioned=].
It is possible for two values from opposite axes to match at the same time,
but not for opposite edges along the same axis.
May match:
@container scroll-state((stuck: top) and (stuck: left)) { ... }
Will never match:
@container scroll-state((stuck: left) and (stuck: right)) { ... }
none
The ''position/sticky'' container is not shifted in any direction.
top
The ''position/sticky'' container is shifted to stay inside the top edge.
right
The ''position/sticky'' container is shifted to stay inside the right edge.
bottom
The ''position/sticky'' container is shifted to stay inside the bottom edge.
left
The ''position/sticky'' container is shifted to stay inside the left edge.
block-start
The ''position/sticky'' container is shifted to stay inside the [=block-start=] edge.
inline-start
The ''position/sticky'' container is shifted to stay inside the [=inline-start=] edge.
block-end
The ''position/sticky'' container is shifted to stay inside the [=block-end=] edge.
inline-end
The ''position/sticky'' container is shifted to stay inside the [=inline-end=] edge.
Scroll snapping: the '@container/snapped' feature
Name: snapped
For: @container
Value: none | x | y | block | inline | both
Type: discrete
container-queries/scroll-state/scroll-state-snapped-both.html
container-queries/scroll-state/scroll-state-snapped-pseudo.html
The '@container/snapped' [=container feature=] queries whether a [=snap target=]
is, or would be, snapped to its [=scroll snap container=], in the given axis. That is,
it matches any [=snap target=] that the {{scrollsnapchanging}} event is fired for.
none
The [=query container=] is not a [=snap target=].
x
'@container/snapped' [=container feature=] matches ''@container/snapped/x''
if the [=query container=] is a horizontal [=snap target=] for its [=scroll container=].
y
'@container/snapped' [=container feature=] matches ''@container/snapped/y''
if the [=query container=] is a vertical [=snap target=] for its [=scroll container=].
block
'@container/snapped' [=container feature=] matches ''@container/snapped/block''
if the [=query container=] is a [=snap target=] for its [=scroll container=].
in the block direction of the [=scroll snap container=].
inline
'@container/snapped' [=container feature=] matches ''@container/snapped/inline''
if the [=query container=] is a [=snap target=] for its [=scroll container=]
in the inline direction of the [=scroll snap container=].
both
'@container/snapped' [=container feature=] matches ''both''
if the [=query container=] is a [=snap target=] for its [=scroll container=]
in both directions of the [=scroll snap container=].
Scrollable: the '@container/scrollable' feature
Name: scrollable
For: @container
Value: none | top | right | bottom | left | block-start | inline-start | block-end | inline-end | x | y | block | inline
Type: discrete
container-queries/scroll-state/scroll-state-scrollable-axis.html
container-queries/scroll-state/scroll-state-scrollable-body-001.html
container-queries/scroll-state/scroll-state-scrollable-body-002.html
container-queries/scroll-state/scroll-state-scrollable-layout-change-002.html
container-queries/scroll-state/scroll-state-scrollable-pseudo.html
container-queries/scroll-state/scroll-state-scrollable-root.html
The '@container/scrollable' [=container feature=] queries whether a
[=scroll container=] has clipped [=scrollable overflow rectangle=] content
in the given direction which is reachable through user initiated scrolling.
That is, '@container/scrollable' does not match for a ''overflow/hidden''
container, nor for a [=unreachable scrollable overflow region=].
The logical values map to physical based on the direction and writing-mode of
the [=query container=]. None of the values match if the container is not a
[=scroll container=].
none
The [=scroll container=] does not have [=scrollable overflow=] in any direction.
top
The [=scroll container=] has [=scrollable overflow=] past the top edge.
right
The [=scroll container=] has [=scrollable overflow=] past the right edge.
bottom
The [=scroll container=] has [=scrollable overflow=] past the bottom edge.
left
The [=scroll container=] has [=scrollable overflow=] past the left edge.
block-start
The [=scroll container=] has [=scrollable overflow=] past the [=block-start=] edge.
inline-start
The [=scroll container=] has [=scrollable overflow=] past the [=inline-start=] edge.
block-end
The [=scroll container=] has [=scrollable overflow=] past the [=block-end=] edge.
inline-end
The [=scroll container=] has [=scrollable overflow=] past the [=inline-end=] edge.
x
The [=scroll container=] has horizontally [=scrollable overflow=].
y
The [=scroll container=] has vertically [=scrollable overflow=].
block
The [=scroll container=] has [=scrollable overflow=] in its block direction.
inline
The [=scroll container=] has [=scrollable overflow=] in its inline direction.
Scrolled: the '@container/scrolled' feature
Name: scrolled
For: @container
Value: none | top | right | bottom | left | block-start | inline-start | block-end | inline-end | x | y | block | inline
Type: discrete
container-queries/scroll-state/scroll-state-scrolled-arrow-key-scroll.html
container-queries/scroll-state/scroll-state-scrolled-home-end-scroll.html
container-queries/scroll-state/scroll-state-scrolled-hv.html
container-queries/scroll-state/scroll-state-scrolled-keyboard-scroll-on-body.html
container-queries/scroll-state/scroll-state-scrolled-keyboard-scroll-on-root.html
container-queries/scroll-state/scroll-state-scrolled-mouse-drag-scroll.html
container-queries/scroll-state/scroll-state-scrolled-multiple-scrollers.html
container-queries/scroll-state/scroll-state-scrolled-programmatic-absolute-scrolls.html
container-queries/scroll-state/scroll-state-scrolled-programmatic-relative-scrolls.html
container-queries/scroll-state/scroll-state-scrolled-pu-pd-scroll.html
container-queries/scroll-state/scroll-state-scrolled-scrollbar-button-clicks.html
container-queries/scroll-state/scroll-state-scrolled-scrollbar-track-clicks.html
container-queries/scroll-state/scroll-state-scrolled-spacebar-scroll.html
container-queries/scroll-state/scroll-state-scrolled-user-touch-scroll.html
container-queries/scroll-state/scroll-state-scrolled-wheel-scroll.html
container-queries/scroll-state/scroll-state-scrolled-wm.html
container-queries/scroll-state/at-container-scrolled-parsing.html
container-queries/scroll-state/at-container-scrolled-serialization.html
For a [=query container=] that is a [=scroll container=],
the '@container/scrolled' [=container feature=] queries the direction of its most recent [=relative scroll=].
The logical values map to physical based on the direction and writing-mode of the [=query container=].
None of the values match if the container is not a [=scroll container=].
none
The [=query container=] has not had a [=relative scroll=] yet.
top
The most recent [=relative scroll=] was upwards.
right
The most recent [=relative scroll=] was to the right.
bottom
The most recent [=relative scroll=] was downwards.
left
The most recent [=relative scroll=] was to the left.
block-start
The most recent [=relative scroll=] was towards the [=block-start=] direction.
inline-start
The most recent [=relative scroll=] was towards the [=inline-start=] direction.
block-end
The most recent [=relative scroll=] was towards the [=block-end=] direction.
inline-end
The most recent [=relative scroll=] was towards the [=inline-end=] direction.
x
The most recent [=relative scroll=] was in the horizontal direction.
y
The most recent [=relative scroll=] was in the vertical direction.
block
The most recent [=relative scroll=] was in the block direction.
inline
The most recent [=relative scroll=] was in the inline direction.
Container Relative Lengths: the ''cqw'', ''cqh'', ''cqi'', ''cqb'', ''cqmin'', ''cqmax'' units
Container query length units
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:
Informative Summary of Container Units
unit
relative to
''cqw''
1% of a [=query container=]’s [=width=]
''cqh''
1% of a [=query container=]’s [=height=]
''cqi''
1% of a [=query container=]’s [=inline size=]
''cqb''
1% of a [=query container=]’s [=block size=]
''cqmin''
The smaller value of ''cqi'' or ''cqb''
''cqmax''
The larger value of ''cqi'' or ''cqb''
container-queries/container-units-auto.html
container-queries/container-units-selection-pseudo.html
For each element,
[=container query length=] units are evaluated
using the same rules 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 computed values.
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=]:
/* 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); }
}
Defining Custom Support Queries: the ''@supports-condition'' rule
The @supports-condition [=at-rule=] is a [=conditional group rule=] that allows authors to define and name a [=supports query=] for later reuse,
creating a named supports condition.
This enables complex or frequently-used feature queries to be referenced by name,
improving maintainability and readability.
@supports-condition <> {
<>
}
at-supports-selector-details-content-before.html
at-supports-selector-details-content.html
Where <> is an <> that defines the name of the supports query.
Anything inside the block is evaluated to test whether the user agent supports the features used.
The contents do not have any effect on the document's rendering.
Once defined, the named supports condition can be used in subsequent ''@supports'' or ''@when'' conditions.
If multiple ''@supports-condition'' rules are defined with the same name,
the last one in document order wins, and all preceding ones are ignored.
For example, we can define a supports query checking multiple properties at once:
@supports-condition --thicker-underlines {
text-decoration-thickness: 0.2em;
text-underline-offset: 0.3em;
}
/* Equivalent to (text-decoration-thickness: 0.2em) and (text-underline-offset: 0.3em) */
@supports (--thicker-underlines) {
a {
text-decoration: underline;
text-decoration-thickness: 0.2em;
text-underline-offset: 0.3em;
}
}
''@supports-condition'' rules are allowed before ''@import'' and ''@namespace'' rules (after the ''@charset'' rule, if any).
As support queries can contain arbitrary declarations,
they can be used to detect support for complex features such as nesting:
Issue: The name of the at-rule is under discussion.
Alternatives include ''@supports-query'', ''@supports-test'', and ''@custom-supports''.
The name should be consistent with the one chosen for custom media queries.
APIs
The CSSContainerRule interface
The {{CSSContainerRule}} interface represents an ''@container'' rule.
Issue: We should try to remove {{CSSContainerRule/containerName}} and
{{CSSContainerRule/containerQuery}}, since they don't deal with multiple
conditions correctly.
container-queries/container-rule-cssom.html
conditionText of type CSSOMString (CSSContainerRule-specific definition for attribute on CSSConditionRule)
The conditionText attribute (defined on the CSSConditionRule parent rule),
on getting, must return a value as follows:
1. Let |conditions| be the result of getting the {{CSSContainerRule/conditions}} attribute.
1. Let |first| be true.
1. Let |result| be the empty string.
1. [=list/For each=] |condition| in |conditions|:
1. If |first| is false, append ", " to |result|.
1. Set |first| to false.
1. If |condition|'s {{CSSContainerCondition/name}} is not empty:
1. Append |condition|'s {{CSSContainerCondition/name}} to |result|.
1. If |condition|'s {{CSSContainerCondition/query}} is not empty,
append a single space to |result|.
1. Append |condition|'s {{CSSContainerCondition/query}} to |result|.
1. Return |result|
containerName of type CSSOMString
The containerName attribute, on getting, must return a value as follows:
1. Let |conditions| be the result of getting the {{CSSContainerRule/conditions}} attribute.
1. If the length of |conditions| is 1:
1. Return the only |conditions| item's {{CSSContainerCondition/name}}.
1. return "".
containerQuery of type CSSOMString
The containerQuery attribute,
on getting, must return a value as follows:
1. Let |conditions| be the result of getting the {{CSSContainerRule/conditions}} attribute.
1. If the length of |conditions| is 1:
1. Return the only |conditions| item's {{CSSContainerCondition/query}}.
1. Return "".
conditions of type FrozenArray<CSSContainerCondition?>
The conditions attribute, on getting,
must return a value as follows:
1. Let |result| be an empty [=list=].
1. [=list/For each=] <> |condition| specified in the rule:
1. Let |dict| be a new {{CSSContainerCondition}} with
{{CSSContainerCondition/name}} set to the
serialized <>
of |condition| if specified, or "" otherwise,
and {{CSSContainerCondition/query}} set to the
<> specified in |condition|
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 <> 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.
1. [=list/Append=] |dict| to |result|.
1. Return |result|.
Issue(6205): Container Queries should have a matchContainer 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 resizeObserver,
but it provides the additional Container Query syntax and features.
The CSSSupportsConditionRule interface
The {{CSSSupportsConditionRule}} interface represents an ''@supports-condition'' rule.
This attribute is the name of the [=named supports condition=].
Security Considerations
No security issues have been raised against this document
Privacy Considerations
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
fingerprinting of the user.
Moved container queries to this specification, from CSS Contain 3 (#10433)
Imported the definitions of <font-format> and <font-tech> from CSS Fonts 4, rather than duplicating them in this specification (#8110)
Updated to use the new parsing algorithm names and block production names
Corrected a typo in the grammar of <font-format>
Corrected extra spaces in the font-tech and font-format productions (#7369)
Additions since Level 4
Added ''@when'' and ''@else''.
Extended [=supports queries=] to express font capabilities
via ''font-tech()'' and ''font-format()''.
Extended [=supports queries=] to express at-rule capabilities
via ''at-rule()''.
Extended [=supports queries=] to express named features
via ''named-feature()''.
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.)
Added ''@supports-condition'' at-rule and related {{CSSSupportsConditionRule}} interface.
Acknowledgments
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.
at-media-001.html
at-media-002.html
at-media-003.html
at-media-content-001.html
at-media-content-002.html
at-media-content-003.html
at-media-content-004.html
at-media-dynamic-001.html
at-media-whitespace-optional-001.html
at-media-whitespace-optional-002.html
at-supports-001.html
at-supports-002.html
at-supports-003.html
at-supports-004.html
at-supports-005.html
at-supports-006.html
at-supports-007.html
at-supports-008.html
at-supports-009.html
at-supports-010.html
at-supports-011.html
at-supports-012.html
at-supports-013.html
at-supports-014.html
at-supports-015.html
at-supports-016.html
at-supports-017.html
at-supports-018.html
at-supports-019.html
at-supports-020.html
at-supports-021.html
at-supports-022.html
at-supports-023.html
at-supports-024.html
at-supports-025.html
at-supports-026.html
at-supports-027.html
at-supports-028.html
at-supports-029.html
at-supports-030.html
at-supports-031.html
at-supports-032.html
at-supports-033.html
at-supports-034.html
at-supports-035.html
at-supports-036.html
at-supports-037.html
at-supports-038.html
at-supports-039.html
at-supports-043.html
at-supports-044.html
at-supports-045.html
at-supports-046.html
at-supports-048.html
at-supports-content-001.html
at-supports-content-002.html
at-supports-content-003.html
at-supports-content-004.html
at-supports-font-format-001.html
at-supports-font-tech-001.html
at-supports-namespace-001.html
at-supports-namespace-002.html
at-supports-selector-001.html
at-supports-selector-002.html
at-supports-selector-003.html
at-supports-selector-004.html
at-supports-selector-detecting-invalid-in-logical-combinations.html
at-supports-selector-file-selector-button.html
at-supports-selector-placeholder.html
at-supports-whitespace.html
css-supports-001.xht
css-supports-002.xht
css-supports-003.xht
css-supports-004.xht
css-supports-005.xht
css-supports-006.xht
css-supports-007.xht
css-supports-008.xht
css-supports-009.xht
css-supports-010.xht
css-supports-011.xht
css-supports-012.xht
css-supports-013.xht
css-supports-014.xht
css-supports-015.xht
css-supports-016.xht
css-supports-017.xht
css-supports-018.xht
css-supports-019.xht
css-supports-020.xht
css-supports-021.xht
css-supports-022.xht
css-supports-023.xht
css-supports-024.xht
css-supports-025.xht
css-supports-026.xht
css-supports-029.xht
css-supports-030.xht
css-supports-031.xht
css-supports-032.xht
css-supports-033.xht
css-supports-034.xht
css-supports-035.xht
css-supports-036.xht
css-supports-037.xht
css-supports-038.xht
css-supports-039.xht
css-supports-040.xht
css-supports-041.xht
css-supports-042.xht
css-supports-043.xht
css-supports-044.xht
css-supports-045.xht
css-supports-046.xht
idlharness.html
js/001.html
js/CSS-supports-CSSStyleDeclaration.html
js/CSS-supports-L3.html
js/CSS-supports-L4.html
js/CSS-supports-selector-detecting-invalid-in-logical-combinations.html
js/conditional-CSSGroupingRule.html
js/supports-conditionText.html
js/CSS-supports-details-content-pseudo-parsing.html
container-queries/crashtests/chrome-bug-385317081-crash.html
container-queries/crashtests/chrome-bug-439886903-crash.html
container-queries/position-sticky-crash.html