CSS at-ruleAt-rules

@container

Applies styles based on the size of a container instead of the whole window. A component adapts to the space it gets in the layout.

On this page

Example

#
CSS
.slot {
  container-type: inline-size;
}

.card {
  display: grid;
  gap: 10px;
}

@container (width >= 240px) {
  .card {
    grid-template-columns: 96px 1fr;
    align-items: center;
  }
}
Preview

Both cards have the same HTML and the same styles. The left column is 180 px wide, so the card is vertical, while the right one is over 240 px wide and the card lays out horizontally. On a phone the right column drops below the left one, but it is still wide enough for the horizontal layout.

Definition and usage

#

The @container rule works like @media, but instead of the window width it checks the size of a chosen ancestor, the container. This way the same card can be vertical in a narrow sidebar and horizontal in the wide main content. You move the component elsewhere on the page and it adapts to the available space on its own.

First you have to designate the container. The container-type: inline-size property tells the browser to track its width, and container-type: size tracks the height as well. The optional container-name gives it a name, and the container: card / inline-size shorthand sets the name and type at once. A @container (width >= 400px) query targets the nearest ancestor that is a container, and @container card (width >= 400px) targets the nearest one with that name.

Rules inside @container apply only to descendants of the container, never to the container itself, because the container’s size cannot depend on styles that depend on that size. For the same reason, the container’s width no longer comes from its content: an element sized to its content, such as an inline-block or a float, can shrink to zero. With container-type: size you also have to set the height yourself.

Inside a container, container query units are available: cqi is 1% of the container’s width, cqb is 1% of its height, and cqmin and cqmax are the smaller and larger of those dimensions. A heading with font-size: clamp(1rem, 6cqi, 2rem) grows with the card, not with the window.

Syntax

#
Syntax
.parent { container-type: inline-size; container-name: <name>; }

@container <name>? (<size condition>) {
  selector { property: value; }
}

Query variants

#
  • (width >= 240px)

    the container is at least 240 px

    When the container is at least 240 px wide, the image sits next to the text. Drag the bottom right corner of the frame to the left and the card returns to the vertical layout.
  • (width < 200px)

    the container is narrower than 200 px

    In a very narrow container the description disappears and the title shrinks. Narrow the frame below 200 px by dragging its bottom right corner to see it.
  • lesson (width >= 240px)

    the nearest container named lesson

    A query with a name skips containers with other names and looks for the nearest ancestor named lesson. It is useful when containers are nested and you want to query a specific one, for example the page column.
  • cqi

    1% of the container width

    A container query unit. The title is 7% of the container’s width, so it grows and shrinks with the frame, and clamp() keeps it within reasonable limits. Drag the corner of the frame and watch the text.

Query variants in practice

#

(width >= 240px)

When the container is at least 240 px wide, the image sits next to the text. Drag the bottom right corner of the frame to the left and the card returns to the vertical layout.
@container (width >= 240px) {
  .card {
    grid-template-columns: 72px 1fr;
    align-items: center;
  }
}

(width < 200px)

In a very narrow container the description disappears and the title shrinks. Narrow the frame below 200 px by dragging its bottom right corner to see it.
@container (width < 200px) {
  .meta { display: none; }
  .title { font-size: 14px; }
}

lesson (width >= 240px)

A query with a name skips containers with other names and looks for the nearest ancestor named lesson. It is useful when containers are nested and you want to query a specific one, for example the page column.
.demo { container-name: lesson; }

@container lesson (width >= 240px) {
  .card {
    grid-template-columns: 72px 1fr;
    align-items: center;
    background: #1e1b4b;
  }
}

cqi

A container query unit. The title is 7% of the container’s width, so it grows and shrinks with the frame, and clamp() keeps it within reasonable limits. Drag the corner of the frame and watch the text.
.title {
  font-size: clamp(14px, 7cqi, 26px);
}

More examples

#
A named container and a heading in cqi units
CSS
.hero {
  container: hero / inline-size;
}

.hero h2 {
  font-size: clamp(1.1rem, 7cqi, 2.2rem);
}

@container hero (width < 320px) {
  .hero .actions {
    flex-direction: column;
  }
}
Preview

Drag the bottom right corner of the frame. The heading scales with the cqi unit, and when the container gets narrower than 320 px, the buttons stack one below the other.

Browser support

#

Widely available · since 2023

Works in all modern browsers, phones included. You can use it without worry.

  • Chrome
  • Edge
  • Firefox
  • Safari

Good practices

#
  • Make an element whose width comes from the layout the container: a grid column, a section, or a slot for a component. Usually do not mark the card itself as a container, only its wrapper.
  • A @container rule styles descendants only. If you want to change the look of the container itself, add a wrapping element inside and style that.
  • The division of roles is simple: @media for page-level decisions, such as the column layout and navigation, and @container for components used in different places.

Related entries

#

Practise it in lessons

#

Spotted a mistake or missing an example? Write to us.