CSS Conditional Rules Module Level 5

W3C Working Draft,

More details about this document
This version:
https://www.w3.org/TR/2024/WD-css-conditional-5-20240723/
Latest published version:
https://www.w3.org/TR/css-conditional-5/
Editor's Draft:
https://drafts.csswg.org/css-conditional-5/
History:
https://www.w3.org/standards/history/css-conditional-5/
Feedback:
CSSWG Issues Repository
Inline In Spec
Editors:
L. David Baron (Mozilla)
Elika J. Etemad / fantasai (Apple)
Chris Lilley (W3C)
Miriam E. Suzanne (Invited Expert)
Suggest an Edit for this Spec:
GitHub Editor
Delta Spec:
yes

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.

CSS is a language for describing the rendering of structured documents (such as HTML and XML) on screen, on paper, etc.

Status of this document

This section describes the status of this document at the time of its publication. A list of current W3C publications and the latest revision of this technical report can be found in the W3C technical reports index at https://www.w3.org/TR/.

This document was published by the CSS Working Group as a Working Draft using the Recommendation track. Publication as a Working Draft does not imply endorsement by W3C and its Members.

This is a draft document and may be updated, replaced or obsoleted by other documents at any time. It is inappropriate to cite this document as other than work in progress.

Please send feedback by filing issues in GitHub (preferred), including the spec code “css-conditional” in the title, like this: “[css-conditional] …summary of comment…”. All issues and comments are archived. Alternately, feedback can be sent to the (archived) public mailing list www-style@w3.org.

This document is governed by the 03 November 2023 W3C Process Document.

This document was produced by a group operating under the W3C Patent Policy. W3C maintains a public list of any patent disclosures made in connection with the deliverables of the group; that page also includes instructions for disclosing a patent. An individual who has actual knowledge of a patent which the individual believes contains Essential Claim(s) must disclose the information in accordance with section 6 of the W3C Patent Policy.

1. Introduction

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

2. Extensions to the @supports rule

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

<supports-feature> = <supports-selector-fn> | <supports-font-tech-fn>
                    | <supports-font-format-fn> | <supports-decl>
<supports-font-tech-fn> = font-tech( <font-tech> )
<supports-font-format-fn> = font-format( <font-format> )
<supports-font-tech-fn>

The result is true if the UA supports the font tech provided as an argument to the function.

<supports-font-format-fn>

The result is true if the UA supports the font format provided as an argument to the function.

2.1. Extensions to the definition of support

A CSS processor is considered to support a font tech when it is capable of utilizing the specified CSS Fonts 4 § 11.1 Font tech 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 § 11.2 Font formats in layout and rendering, and this format is not specified as a <string>.

3. 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 <boolean-condition> {
  <rule-list>
}

Where <boolean-condition> is a boolean algebra a la Media Queries 4 § 3 Syntax, but with media() and supports() functions as leaves.

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:

media() = media( [ <mf-plain> | <mf-boolean> | <mf-range> ] )
supports() = supports( <declaration> )

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

4. 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 rules and guarantee that only the first one that matches will evaluate its condition as true. It is defined as:

@else <boolean-condition>? {
  <rule-list>
}

@else is interpreted identically to @when. If its <boolean-condition> 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.

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.

@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); }
}

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.

@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); }
}

5. Container Queries

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 shadow-including descendants can be conditioned by querying against it, using the @container conditional group rule.

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 selectors with pseudo elements, query containers can be established by the shadow-including inclusive ancestors of the ultimate originating element.

It follows that:
A ::before selector querying the size of the originating element:
<style>
  #container {
    width: 100px;
    container-type: inline-size;
  }
  @container (inline-size < 150px) {
    #inner::before {
      content: "BEFORE";
    }
  }
</style>
<div id=container>
  <span id=inner></span>
</div>
A ::slotted() selector for styling a shadow host child can query a container in the shadow tree:
<div id=host style="width:200px">
  <template shadowroot=open>
    <style>
      #container {
        width: 100px;
        container-type: inline-size;
      }
      @container (inline-size < 150px) {
        ::slotted(span) {
          color: green;
        }
      }
    </style>
    <div id=container>
      <slot />
    </div>
  </template>
  <span id=slotted>Green</span>
</div>

5.1. Creating Query Containers: the container-type property

Name: container-type
Value: normal | size | inline-size
Initial: normal
Applies to: all elements
Inherited: no
Percentages: n/a
Computed value: specified keyword
Canonical order: per grammar
Animation type: not animatable

The container-type property establishes the element as a query container 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:

size
Establishes a query container for container size queries on both the inline and block axis. Applies layout containment, style containment, and size containment to the principal box.
inline-size
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.
normal
The element is not a query container for any container size 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:
aside, main {
  container-type: inline-size;
}

h2 { font-size: 1.2em; }

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

The 40em value used in the query condition is relative to the computed value of font-size on the relevant query container.

Containers can also expose computed style values for querying. This can be useful for toggling behavior across multiple properties:
section {
  container-type: style;
}

@container style(--cards: small) {
  article {
    border: thin solid silver;
    border-radius: 0.5em;
    padding: 1em;
  }
}

5.2. Naming Query Containers: the container-name property

Name: container-name
Value: none | <custom-ident>+
Initial: none
Applies to: all elements
Inherited: no
Percentages: n/a
Computed value: the keyword none, or an ordered list of identifiers
Canonical order: per grammar
Animation type: not animatable

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.

none
The query container has no query container name.
<custom-ident>
Specifies a query container name as an identifier. The keywords none, and, not, and or are excluded from this <custom-ident>.
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.
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; }
}

5.3. Creating Named Containers: the container shorthand

Name: container
Value: <'container-name'> [ / <'container-type'> ]?
Initial: see individual properties
Applies to: see individual properties
Inherited: see individual properties
Percentages: see individual properties
Computed value: see individual properties
Animation type: see individual properties
Canonical order: per grammar

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.

We can define both a container-type and container-name using the shorthand syntax:
main {
  container: my-layout / size;
}

.grid-item {
  container: my-component / inline-size;
}

5.4. Container Queries: the @container rule

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 <block-contents> block of an @container rule are 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 <container-condition># {
  <block-contents>
}

where:

<container-condition> = [ <container-name> ]? <container-query>
<container-name> = <custom-ident>
<container-query>     = not <query-in-parens>
                      | <query-in-parens> [ [ and <query-in-parens> ]* | [ or <query-in-parens> ]* ]
<query-in-parens>     = ( <container-query> )
                      | ( <size-feature> )
                      | style( <style-query> )
                      | <general-enclosed>

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

The keywords 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 features, 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 any of its component <container-condition>s are true, and false only if all of its component <container-condition>s are false.

As with media queries, we can string together multiple queries in a single condition:
@container card (inline-size > 30em) and style(--responsive: true) {
  /* styles */
}

The styles above will only be applied if there is an ancestor container named "card" that meets both the inline-size and style conditions.

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

@container card (inline-size > 30em), style(--large: true) {
  /* styles */
}

The styles above will be applied if there is an ancestor container named "card" that meets the inline-size condition or the nearest style container meets the 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 <container-condition>s into a single query.

Using a single comma-separated container query, we can query multiple containers:
@container card (inline-size > 30em), style(--responsive: true) {
  /* styles */
}

The styles above will apply for an element inside either a container named "card" that meets the inline-size condition, or a container meeting the style condition.

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

@container card (inline-size > 30em) {
  @container style(--responsive: true) {
    /* styles */
  }
}

The styles above will only be applied if there is both an ancestor container named "card" that meets the inline-size condition, and an ancestor container meeting the 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.

5.5. 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 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;
}
<main>
  <div id=container>
    <div id=inner>Inner</div>
  </div>
  <div id=sibling>Sibling</div>
</main>

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

6. Container Features

A container feature queries a specific aspect of a query container.

6.1. 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 (<size-feature>) that each query a single, specific dimensional feature of the query container. The syntax of a <size-feature> 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 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.

For example, query containers with different font-sizes will evaluate em-based queries relative to their own font sizes:
aside, main {
  container-type: inline-size;
}

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

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

The 40em value used in the query condition is relative to the computed value of font-size on the relevant query container:

Similarly, query containers will evaluate var()-based queries relative to their own computed value of the custom property:
aside, main {
  container-type: inline-size;
}

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

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

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:

6.1.1. Width: the width feature

Name: width
For: @container
Value: <length>
Type: range

The width container feature queries the width of the query container’s content box.

6.1.2. Height: the height feature

Name: height
For: @container
Value: <length>
Type: range

The height container feature queries the height of the query container’s content box.

6.1.3. Inline-size: the inline-size feature

Name: inline-size
For: @container
Value: <length>
Type: range

The inline-size container feature queries the size of the query container’s content box in the query container’s inline axis.

6.1.4. Block-size: the block-size feature

Name: block-size
For: @container
Value: <length>
Type: range

The block-size container feature queries the size of the query container’s content box in the query container’s block axis.

6.1.5. Aspect-ratio: the aspect-ratio feature

Name: aspect-ratio
For: @container
Value: <ratio>
Type: range

The aspect-ratio container feature is defined as the ratio of the value of the width container feature to the value of the height container feature.

6.1.6. Orientation: the orientation feature

Name: orientation
For: @container
Value: portrait | landscape
Type: discrete
portrait
The orientation container feature is portrait when the value of the height container feature is greater than or equal to the value of the width container feature.
landscape
Otherwise orientation is landscape.

6.2. 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 (<style-feature>) that each query a single, specific property of the query container. The syntax of a <style-feature> 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 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 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 with respect to the query container, the same as other values.

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

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 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); }
}

8. APIs

8.1. The CSSContainerRule interface

The CSSContainerRule interface represents a @container rule.

[Exposed=Window]
interface CSSContainerRule : CSSConditionRule {
    readonly attribute CSSOMString containerName;
    readonly attribute CSSOMString containerQuery;
};
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:
The @container rule has an associated <container-name>
The result of getting the containerName and containerQuery attributes, joined by a single whitespace.
Otherwise
The result of getting the containerQuery attribute.
containerName of type CSSOMString
The containerName attribute, on getting, must return a value as follows:
The @container rule has an associated <container-name>
The result of serializing that <container-name>.
Otherwise
An empty string.
containerQuery of type CSSOMString
The containerQuery 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.

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. [Issue #6205]

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.

Changes

Changes since the First Public Working Draft of 21 December 2021

Additions since Level 4

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.

Conformance

Document conventions

Conformance requirements are expressed with a combination of descriptive assertions and RFC 2119 terminology. The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in the normative parts of this document are to be interpreted as described in RFC 2119. However, for readability, these words do not appear in all uppercase letters in this specification.

All of the text of this specification is normative except sections explicitly marked as non-normative, examples, and notes. [RFC2119]

Examples in this specification are introduced with the words “for example” or are set apart from the normative text with class="example", like this:

This is an example of an informative example.

Informative notes begin with the word “Note” and are set apart from the normative text with class="note", like this:

Note, this is an informative note.

Advisements are normative sections styled to evoke special attention and are set apart from other normative text with <strong class="advisement">, like this: UAs MUST provide an accessible alternative.

Conformance classes

Conformance to this specification is defined for three conformance classes:

style sheet
A CSS style sheet.
renderer
A UA that interprets the semantics of a style sheet and renders documents that use them.
authoring tool
A UA that writes a style sheet.

A style sheet is conformant to this specification if all of its statements that use syntax defined in this module are valid according to the generic CSS grammar and the individual grammars of each feature defined in this module.

A renderer is conformant to this specification if, in addition to interpreting the style sheet as defined by the appropriate specifications, it supports all the features defined by this specification by parsing them correctly and rendering the document accordingly. However, the inability of a UA to correctly render a document due to limitations of the device does not make the UA non-conformant. (For example, a UA is not required to render color on a monochrome monitor.)

An authoring tool is conformant to this specification if it writes style sheets that are syntactically correct according to the generic CSS grammar and the individual grammars of each feature in this module, and meet all other conformance requirements of style sheets as described in this module.

Partial implementations

So that authors can exploit the forward-compatible parsing rules to assign fallback values, CSS renderers must treat as invalid (and ignore as appropriate) any at-rules, properties, property values, keywords, and other syntactic constructs for which they have no usable level of support. In particular, user agents must not selectively ignore unsupported component values and honor supported values in a single multi-value property declaration: if any value is considered invalid (as unsupported values must be), CSS requires that the entire declaration be ignored.

Implementations of Unstable and Proprietary Features

To avoid clashes with future stable CSS features, the CSSWG recommends following best practices for the implementation of unstable features and proprietary extensions to CSS.

Non-experimental implementations

Once a specification reaches the Candidate Recommendation stage, non-experimental implementations are possible, and implementors should release an unprefixed implementation of any CR-level feature they can demonstrate to be correctly implemented according to spec.

To establish and maintain the interoperability of CSS across implementations, the CSS Working Group requests that non-experimental CSS renderers submit an implementation report (and, if necessary, the testcases used for that implementation report) to the W3C before releasing an unprefixed implementation of any CSS features. Testcases submitted to W3C are subject to review and correction by the CSS Working Group.

Further information on submitting testcases and implementation reports can be found from on the CSS Working Group’s website at https://www.w3.org/Style/CSS/Test/. Questions should be directed to the public-css-testsuite@w3.org mailing list.

Index

Terms defined by this specification

Terms defined by reference

References

Normative References

[CSS-ANIMATIONS-1]
David Baron; et al. CSS Animations Level 1. 2 March 2023. WD. URL: https://www.w3.org/TR/css-animations-1/
[CSS-BOX-4]
Elika Etemad. CSS Box Model Module Level 4. 1 April 2024. WD. URL: https://www.w3.org/TR/css-box-4/
[CSS-CASCADE-4]
Elika Etemad; Tab Atkins Jr.. CSS Cascading and Inheritance Level 4. 13 January 2022. CR. URL: https://www.w3.org/TR/css-cascade-4/
[CSS-CASCADE-5]
Elika Etemad; Miriam Suzanne; Tab Atkins Jr.. CSS Cascading and Inheritance Level 5. 13 January 2022. CR. URL: https://www.w3.org/TR/css-cascade-5/
[CSS-CONDITIONAL-3]
David Baron; Elika Etemad; Chris Lilley. CSS Conditional Rules Module Level 3. 13 January 2022. CR. URL: https://www.w3.org/TR/css-conditional-3/
[CSS-CONDITIONAL-4]
David Baron; Elika Etemad; Chris Lilley. CSS Conditional Rules Module Level 4. 17 February 2022. CR. URL: https://www.w3.org/TR/css-conditional-4/
[CSS-CONDITIONAL-5]
David Baron; Elika Etemad; Chris Lilley. CSS Conditional Rules Module Level 5. 21 December 2021. WD. URL: https://www.w3.org/TR/css-conditional-5/
[CSS-CONTAIN-2]
Tab Atkins Jr.; Florian Rivoal; Vladimir Levin. CSS Containment Module Level 2. 17 September 2022. WD. URL: https://www.w3.org/TR/css-contain-2/
[CSS-CONTAIN-3]
Tab Atkins Jr.; Florian Rivoal; Miriam Suzanne. CSS Containment Module Level 3. 18 August 2022. WD. URL: https://www.w3.org/TR/css-contain-3/
[CSS-DISPLAY-3]
Elika Etemad; Tab Atkins Jr.. CSS Display Module Level 3. 30 March 2023. CR. URL: https://www.w3.org/TR/css-display-3/
[CSS-FONTS-4]
Chris Lilley. CSS Fonts Module Level 4. 1 February 2024. WD. URL: https://www.w3.org/TR/css-fonts-4/
[CSS-FONTS-5]
Chris Lilley. CSS Fonts Module Level 5. 6 February 2024. WD. URL: https://www.w3.org/TR/css-fonts-5/
[CSS-SIZING-3]
Tab Atkins Jr.; Elika Etemad. CSS Box Sizing Module Level 3. 17 December 2021. WD. URL: https://www.w3.org/TR/css-sizing-3/
[CSS-SYNTAX-3]
Tab Atkins Jr.; Simon Sapin. CSS Syntax Module Level 3. 24 December 2021. CR. URL: https://www.w3.org/TR/css-syntax-3/
[CSS-TRANSITIONS-1]
David Baron; et al. CSS Transitions. 11 October 2018. WD. URL: https://www.w3.org/TR/css-transitions-1/
[CSS-VALUES-4]
Tab Atkins Jr.; Elika Etemad. CSS Values and Units Module Level 4. 12 March 2024. WD. URL: https://www.w3.org/TR/css-values-4/
[CSS-VARIABLES-1]
Tab Atkins Jr.. CSS Custom Properties for Cascading Variables Module Level 1. 16 June 2022. CR. URL: https://www.w3.org/TR/css-variables-1/
[CSS-WRITING-MODES-4]
Elika Etemad; Koji Ishii. CSS Writing Modes Level 4. 30 July 2019. CR. URL: https://www.w3.org/TR/css-writing-modes-4/
[CSSOM-1]
Daniel Glazman; Emilio Cobos Álvarez. CSS Object Model (CSSOM). 26 August 2021. WD. URL: https://www.w3.org/TR/cssom-1/
[CSSOM-VIEW-1]
Simon Pieters. CSSOM View Module. 17 March 2016. WD. URL: https://www.w3.org/TR/cssom-view-1/
[DOM]
Anne van Kesteren. DOM Standard. Living Standard. URL: https://dom.spec.whatwg.org/
[MEDIAQUERIES-4]
Florian Rivoal; Tab Atkins Jr.. Media Queries Level 4. 25 December 2021. CR. URL: https://www.w3.org/TR/mediaqueries-4/
[MEDIAQUERIES-5]
Dean Jackson; et al. Media Queries Level 5. 18 December 2021. WD. URL: https://www.w3.org/TR/mediaqueries-5/
[RFC2119]
S. Bradner. Key words for use in RFCs to Indicate Requirement Levels. March 1997. Best Current Practice. URL: https://datatracker.ietf.org/doc/html/rfc2119
[SELECTORS-4]
Elika Etemad; Tab Atkins Jr.. Selectors Level 4. 11 November 2022. WD. URL: https://www.w3.org/TR/selectors-4/
[WEB-ANIMATIONS-1]
Brian Birtles; et al. Web Animations. 5 June 2023. WD. URL: https://www.w3.org/TR/web-animations-1/
[WEBIDL]
Edgar Chen; Timothy Gu. Web IDL Standard. Living Standard. URL: https://webidl.spec.whatwg.org/

Informative References

[CSS-POSITION-4]
CSS Positioned Layout Module Level 4. Editor's Draft. URL: https://drafts.csswg.org/css-position-4/
[CSS-PSEUDO-4]
Daniel Glazman; Elika Etemad; Alan Stearns. CSS Pseudo-Elements Module Level 4. 30 December 2022. WD. URL: https://www.w3.org/TR/css-pseudo-4/
[CSS-SCOPING-1]
Tab Atkins Jr.; Elika Etemad. CSS Scoping Module Level 1. 3 April 2014. WD. URL: https://www.w3.org/TR/css-scoping-1/
[CSS-SHADOW-PARTS-1]
Tab Atkins Jr.; Fergal Daly. CSS Shadow Parts. 15 November 2018. WD. URL: https://www.w3.org/TR/css-shadow-parts-1/
[CSS22]
Bert Bos. Cascading Style Sheets Level 2 Revision 2 (CSS 2.2) Specification. 12 April 2016. WD. URL: https://www.w3.org/TR/CSS22/

Property Index

Name Value Initial Applies to Inh. %ages Anim­ation type Canonical order Com­puted value
container <'container-name'> [ / <'container-type'> ]? see individual properties see individual properties see individual properties see individual properties see individual properties per grammar see individual properties
container-name none | <custom-ident>+ none all elements no n/a not animatable per grammar the keyword none, or an ordered list of identifiers
container-type normal | size | inline-size normal all elements no n/a not animatable per grammar specified keyword

@container Descriptors

Name Value Initial Type
aspect-ratio <ratio> range
block-size <length> range
height <length> range
inline-size <length> range
orientation portrait | landscape discrete
width <length> range

IDL Index

[Exposed=Window]
interface CSSContainerRule : CSSConditionRule {
    readonly attribute CSSOMString containerName;
    readonly attribute CSSOMString containerQuery;
};

Issues Index

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.
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.
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.
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. [Issue #6205]