Container Queries: Component-Level Responsiveness

13 min read

Responding to a Container, Not the Viewport

Media queries respond to the viewport size. But components are often placed inside grids, sidebars, or modals that are much narrower than the viewport. Container queries let a component adapt to the size of its own parent container — enabling truly reusable, self-contained responsive components.

Establishing a containment context

css

/* Step 1: declare a containment context on the parent */
.card-wrapper {
  container-type: inline-size;
  /* Optional: give it a name to target specifically */
  container-name: card;
}

/* Shorthand */
.card-wrapper {
  container: card / inline-size;
}

Writing container queries

css

/* Default: stacked layout (narrow containers) */
.card {
  display: grid;
  grid-template-columns: 1fr;
  gap: 1rem;
}

/* When the card wrapper is at least 400px wide: go horizontal */
@container card (min-width: 400px) {
  .card {
    grid-template-columns: 120px 1fr;
    align-items: center;
  }

  .card__image {
    aspect-ratio: 1;
  }
}

/* When the card wrapper is at least 600px wide: show extra detail */
@container card (min-width: 600px) {
  .card__meta {
    display: flex;
    gap: 1rem;
  }

  .card__description {
    display: block;
  }
}

Container query units

Container queries introduce their own relative units: cqi (1% of container inline size), cqb (1% of container block size), cqw, cqh, cqmin, cqmax. Use them like vw/vh but relative to the container, not the viewport.

css

.card-wrapper {
  container-type: inline-size;
}

.card__title {
  /* Font grows with the card container, not the viewport */
  font-size: clamp(1rem, 4cqi, 2rem);
}

Container queries vs. media queries

Media query — use for page-level layout changes (columns, sidebars, navbars).
Container query — use for component-level changes (card layout, widget display density).
They complement each other perfectly and can be used in the same stylesheet.

Container queries have baseline support across all modern browsers as of 2023. Start migrating reusable components from media queries to container queries — it makes them trivially droppable into any layout without adjustment.

Ready to test yourself?

Practice CSS— quiz & coding exercises