@container

Baseline 2023

Newly available

Since February 2023, this feature works across the latest devices and browser versions. This feature might not work in older devices or browsers.

The @container CSS at-rule is a conditional group rule that applies styles to a containment context. Style declarations are filtered by a condition and applied to the container if the condition is true. The condition is evaluated when the container changes size.

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. The optional, case-sensitive <container-name> filters the query containers that are targeted by the query.

Once an eligible query container has been selected for an element, each container feature in the <container-condition> is evaluated against that query container.

Syntax

The @container at-rule has the following syntax:

@container <container-condition> {
  <stylesheet>
}

For example:

css
@container (width > 400px) {
  h2 {
    font-size: 1.5em;
  }
}
/* with an optional <container-name> */
@container tall (height > 30rem) {
  h2 {
    line-height: 1.6;
  }
}

Values

<container-condition>

An optional <container-name> and a <container-query>. Styles defined in the <stylesheet> are applied if the condition is true.

<container-name>

Optional. The name of the container that the styles will be applied to when the query evaluates to true, specified as an <ident>.

<container-query>

A set of features that are evaluated against the query container when the size of the container changes.

<stylesheet>

A set of CSS declarations.

Logical keywords in container queries

Logical keywords can be used to define the container condition:

  • and combines two or more conditions.
  • or combines two or more conditions.
  • not negates the condition. Only one 'not' condition is allowed per container query and cannot be used with the and or or keywords.
css
@container (width > 400px) and (height > 400px) {
  /* <stylesheet> */
}

@container (width > 400px) or (height > 400px) {
  /* <stylesheet> */
}

@container not (width < 400px) {
  /* <stylesheet> */
}

Named containment contexts

A containment context can be named using the container-name property.

css
.post {
  container-name: sidebar;
  container-type: inline-size;
}

The shorthand syntax for this is to use container in the form container: <name> / <type>, for example:

css
.post {
  container: sidebar / inline-size;
}

In container queries, the container-name property is used to filter the set of containers to those with a matching query container name:

css
@container sidebar (width > 400px) {
  /* <stylesheet> */
}

Details about usage and naming restrictions are described in the container-name page.

Descriptors

The following descriptors can be used within the container condition:

aspect-ratio

The aspect-ratio of the container calculated as the width to the height of the container expressed as a <ratio> value.

block-size

The block-size of the container expressed as a <length> value.

height

The height of the container expressed as a <length> value.

inline-size

The inline-size of the container expressed as a <length> value.

orientation

The orientation of the container, either landscape or portrait.

width

The width of the container expressed as a <length> value.

Examples

Setting styles based on a container's size

Consider the following example of a card component with a title and some text:

html
<div class="post">
  <div class="card">
    <h2>Card title</h2>
    <p>Card content</p>
  </div>
</div>

A container context can be created using the container-type property, in this case using the inline-size value on the .post class. You can then use the @container at-rule to apply styles to the element with the .card class in a container that's narrower than 650px.

css
/* A container context based on inline size */
.post {
  container-type: inline-size;
}

/* Apply styles if the container is narrower than 650px */
@container (width < 650px) {
  .card {
    width: 50%;
    background-color: gray;
    font-size: 1em;
  }
}

Creating named container contexts

Given the following HTML example which is a card component with a title and some text:

html
<div class="post">
  <div class="card">
    <h2>Card title</h2>
    <p>Card content</p>
  </div>
</div>

First, create a container context using the container-type and container-name properties. The shorthand syntax for this declaration is described in the container page.

css
.post {
  container-type: inline-size;
  container-name: summary;
}

Next, target that container by adding the name to the container query:

css
@container summary (min-width: 400px) {
  .card {
    font-size: 1.5em;
  }
}

Nested container queries

It's not possible to target multiple containers in a single container query. It is possible to nest container queries which has the same effect.

The following query evaluates to true and applies the declared style if the container named summary is wider than 400px and has an ancestor container wider than 800px:

css
@container summary (min-width: 400px) {
  @container (min-width: 800px) {
    /* <stylesheet> */
  }
}

Container style queries

Experimental: This is an experimental technology
Check the Browser compatibility table carefully before using this in production.

Container queries can also evaluate the computed style of the container element. A container style query is a @container query that uses one or more style() functional notations. The boolean syntax and logic combining style features into a style query is the same as for CSS feature queries.

css
@container style(<style-feature>),
    not style(<style-feature>),
    style(<style-feature>) and style(<style-feature>),
    style(<style-feature>) or style(<style-feature>) {
  /* <stylesheet> */
}

The parameter of each style() is a single <style-feature>. A <style-feature> is a valid CSS declaration, a CSS property, or a <custom-property-name>.

css
@container style(--themeBackground),
    not style(background-color: red),
    style(color: green) and style(background-color: transparent),
    style(--themeColor: blue) or style(--themeColor: purple) {
  /* <stylesheet> */
}

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

If the <style-feature> passed as the style() function's argument is a declaration, the style query evaluates to true if the declaration's value is the same as the computed value of that property for the container being queried. Otherwise, it resolves to false.

The following container query checks if the computed_value of the container element's --accent-color is blue:

css
@container style(--accent-color: blue) {
  /* <stylesheet> */
}

Note: If a custom property has a value of blue, the equivalent hexidecimal code #0000ff will not match unless the property has been defined as a color with @property so the browser can properly compare computed values.

Style features that query a shorthand property are true if the computed values match for each of its longhand properties, and false otherwise. For example, @container style(border: 2px solid red) will resolve to true if all 12 longhand properties (border-bottom-style, etc.) that make up that shorthand are true.

The global revert and revert-layer are invalid as values in a <style-feature> and cause the container style query to be false.

Specifications

Specification
CSS Containment Module Level 3
# container-rule

Browser compatibility

BCD tables only load in the browser

See also