Container Queries: Component-Level Responsive Design

Traditional media queries answer the question: 'How wide is the browser window?' Container queries answer: 'How wide is the element I'm living inside?'

This distinction matters enormously for component-based design. A card component might appear in a narrow sidebar (300px wide) and a wide main content area (800px wide) on the same page at the same viewport width. A `@media` query can't distinguish between these two — but a container query can.

This is why container queries are the most significant addition to CSS since flexbox.

/* 1. Define a containment context on the parent */
.card-wrapper {
  container-type: inline-size;
  container-name: card; /* optional, for named queries */
}

/* 2. Query the container from the child */
@container card (min-width: 400px) {
  .card {
    flex-direction: row;
    gap: 24px;
  }

  .card-image {
    width: 200px;
    flex-shrink: 0;
  }
}

`container-type: inline-size` establishes an inline-size containment context — the element becomes a container that its children can query. The `container-name` is optional but useful when components are nested.

Container queries come with their own relative units — similar to viewport units but relative to the nearest container:

.card {
  padding: 5cqi; /* 5% of container inline-size */
  font-size: clamp(1rem, 3cqi, 1.5rem);
}

The available units are: • `cqw` — 1% of container width • `cqh` — 1% of container height • `cqi` — 1% of container inline size • `cqb` — 1% of container block size • `cqmin` — smaller of cqi/cqb • `cqmax` — larger of cqi/cqb

These enable fluid scaling within components without needing `clamp()` with viewport units.

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

.card {
  display: flex;
  flex-direction: column;
  padding: 16px;
  gap: 12px;
}

/* When the card's container is at least 480px wide */
@container (min-width: 480px) {
  .card {
    flex-direction: row;
    align-items: center;
    padding: 24px;
    gap: 24px;
  }

  .card-image {
    width: 180px;
    height: 180px;
    flex-shrink: 0;
  }

  .card-title {
    font-size: 1.25rem;
  }
}

This card layout automatically adapts whether it's in a 2-column grid or a narrow sidebar — with no JavaScript and no new CSS classes.

Style queries are the next frontier — they let you query computed CSS custom property values on a container:

.sidebar {
  --layout: narrow;
  container-type: inline-size;
}

@container style(--layout: narrow) {
  .card-title {
    font-size: 0.875rem;
  }
}

This enables 'smart components' that adapt to semantic context (not just size). Style queries are in Chrome 111+ but not yet widely available — watch this space.

Container Queries (size queries) reached Baseline Widely Available in February 2024.

• Chrome 105+ ✅ • Firefox 110+ ✅ • Safari 16+ ✅ • Edge 105+ ✅

Safe to use in production. No polyfill needed for modern browser targets.

1. Querying the container itself A container cannot query itself. Container queries apply to descendants only. Wrap the component in a parent with `container-type`.

2. Using `container-type: size` unnecessarily `container-type: size` requires both inline and block size containment, which prevents the element from growing to fit its content. Almost always, use `container-type: inline-size` instead.

3. Forgetting containment is inherited A `container-type` applies a containment context — children can't escape it with `position: fixed` or `z-index`. For overlays inside containers, be aware of stacking context implications.

Do container queries replace media queries? No. They complement each other. Use media queries for page-level layout (columns, sidebar presence). Use container queries for component-level adaptation.

Can I use container queries in React/Vue components? Yes — the container and query are pure CSS. The framework has no involvement. Apply `container-type` to the wrapper element and add `@container` styles to the component's CSS.

What happens in browsers that don't support container queries? Styles inside `@container` blocks are simply ignored. Write your base styles (mobile-first) outside the container query and use the query to enhance for larger containers.