query the size of a container

a container has less space available in the surrounding context, you can hide certain elements or use smaller fonts.

Using container queries

To use container queries, you need to declare a containment context on an element so that the browser knows you might want to query the dimensions of this container later. To do this, use the container-type property with a value of size, inline-size, or normal.

These values have the following effects:

size

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

inline-size

The query will be based on the inline 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:

HTMLCopy to Clipboard

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

You can create a containment context using the container-type property:

CSSCopy to Clipboard

.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 than 700px:

CSSCopy to Clipboard

/* Default heading styles for the card title */
.card h2 {
  font-size: 1em;
}

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 than 700px, the font of the card title will be small, and if the card is in a container that's wider than 700px, the font of the card title will be bigger.

/* If the container is larger than 700px */
@container (min-width: 700px) {
  .card h2 {
    font-size: 2em;
  }
}

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 the container-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 name sidebar:

CSSCopy to Clipboard

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

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

CSSCopy to Clipboard

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

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

Shorthand container syntax

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

CSSCopy to Clipboard

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

For more information on this property, see the container 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.

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 either cqi or cqb

• cqmax: The larger value of either cqi or cqb

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

CSSCopy to Clipboard

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

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

Fallbacks for container queries

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

CSSCopy to Clipboard

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

CSSCopy to Clipboard

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

See also

• Media queries

• CSS @container at-rule

• CSS contain property

• CSS container shorthand property

• CSS container-name property

• CSS content-visibility property

• Using container size and style queries

• Say Hello to CSS Container Queries by Ahmad Shadeed

• Container Queries: a Quick Start Guide

• Collection of Container Queries articles

Help improve MDN

Was this page helpful to you?

YesNo

Learn how to contribute.

This page was last modified on Feb 21, 2024 by MDN contributors.

View this page on GitHub • Report a problem with this content