Container queries enable you to apply styles to an element based on certain attributes of its container:

• The container's size.
• Styles applied to the container.
• The container's scroll-state or that of its scrolling ancestor.

Container queries are an alternative tomedia queries, which apply styles to elements based on viewport size or other device characteristics.

This article provides an introduction to using container queries, specifically focusing on size container queries. Other guides discussstyle andscroll-state container queries in detail.

Using container size queries

While container queries apply styles based on the container type, container size queries apply styles specifically based on the container's dimensions. To use container size queries, you need to declare acontainment context on an element so that the browser knows you might want to query the dimensions of this container later.To do this, use thecontainer-type property with a value ofsize,inline-size, ornormal.

These values have the following effects:

size

The query will be based on theinline and block dimensions of the container.Applies layout, style, and sizecontainment to the container.

inline-size

The query will be based on theinline dimensions of the container.Applies layout, style, and inline-size containment to the element.

normal

The element is not a query container for any container size queries, but remains a query container for container style queries.

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

<div>  <div>    <h2>Card title</h2>    <p>Card content</p>  </div></div>

You can create a containment context using thecontainer-type property:

.post {  container-type: inline-size;}

Next, use the@container at-rule to define a container query.The query in the following example will apply styles to elements based on the size of the nearest ancestor with a containment context.Specifically, this query will apply a larger font size for the card title if the container is wider than700px:

/* Default heading styles for the card title */.card h2 {  font-size: 1em;}/* If the container is larger than 700px */@container (width > 700px) {  .card h2 {    font-size: 2em;  }}

Using container queries, the card can be reused in multiple areas of a page without needing to know specifically where it will be placed each time.If the container with the card is narrower than700px, the font of the card title will be small, and if the card is in a container that's wider than700px, the font of the card title will be bigger.

For more information on the syntax of container queries, see the@container page.

Naming containment contexts

In the previous section, a container query applied styles based on the nearest ancestor with a containment context.It's possible to give a containment context a name using thecontainer-name property. Once named, the name can be used in a@container query so as to target a specific container.The following example creates a containment context with the namesidebar:

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

You can then target this containment context using the@container at-rule:

@container sidebar (width > 700px) {  .card {    font-size: 2em;  }}

More information on naming containment contexts is available on thecontainer-name page.

Shorthand container syntax

The shorthand way of declaring a containment context is to use thecontainer property:

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

For more information on this property, see thecontainer reference.

Container query length units

When applying styles to a container using container queries, you can use container query length units.These units specify a length relative to the dimensions of a query container.Components that use units of length relative to their container are more flexible to use in different containers without having to recalculate concrete length values.

If no eligible container is available for the query, the container query length unit defaults to thesmall viewport unit for that axis (sv*).

The container query length units are:

• 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 eithercqi orcqb
• cqmax: The larger value of eithercqi orcqb

The following example uses thecqi unit to set the font size of a heading based on the inline size of the container:

@container (width > 700px) {  .card h2 {    font-size: max(1.5em, 1.23em + 2cqi);  }}

For more information on these units, see theContainer query length units reference.

Fallbacks for container queries

For browsers that don't yet support container queries,grid andflex can be used to create a similar effect for the card component used on this page.The following example uses agrid-template-columns declaration to create a two-column layout for the card component.

.card {  display: grid;  grid-template-columns: 2fr 1fr;}

If you want to use a single-column layout for devices with a smaller viewport, you can use a media query to change the grid template:

@media (width <= 700px) {  .card {    grid-template-columns: 1fr;  }}

See also

• Media queries
• CSS@container at-rule
• CSScontain property
• CSScontainer shorthand property
• CSScontainer-name property
• CSScontent-visibility property
• Using container size and style queries
• Using container scroll-state queries
• Say Hello to CSS Container Queries by Ahmad Shadeed
• Container Queries: a Quick Start Guide
• Collection of Container Queries articles