CSS container queries are production-ready - here's how we use them

Container queries have been 'almost ready for production' for what feels like years. As of mid-2026, all major evergreen browsers have had full support for over 18 months, and the baseline compatibility concern is effectively gone for teams that don't target legacy browsers. We've now shipped container queries in production across our component library and the real-world ergonomics are better than we expected.

The fundamental shift

Media queries ask 'how wide is the viewport?' Container queries ask 'how wide is my parent?' The difference sounds small, but it completely changes how you think about component design. A sidebar card can now define its own responsive behavior - compact at 200px width, expanded at 400px - regardless of where in the layout it's placed. The component is truly self-contained.

/* Define a containment context */
.card-wrapper {
  container-type: inline-size;
  container-name: card;
}

/* Query the container, not the viewport */
@container card (min-width: 400px) {
  .card {
    flex-direction: row;
    gap: 1.5rem;
  }
  .card-image {
    width: 200px;
    flex-shrink: 0;
  }
}

Container queries in Tailwind v4

Tailwind v4 ships first-class container query utilities via the `@container` variant. You mark a container with `@container` on the parent, then use `@sm:`, `@md:`, `@lg:` on children to apply styles at container breakpoints. These map to the same breakpoint values as the viewport variants but react to the nearest named or unnamed `@container` ancestor.

<!-- Parent defines the containment context -->
<div class="@container">
  <!-- Child responds to container width, not viewport -->
  <div class="flex flex-col @md:flex-row gap-4">
    <img class="w-full @md:w-48 shrink-0" />
    <div class="flex-1">
      <h3 class="text-sm @lg:text-base font-semibold">...</h3>
    </div>
  </div>
</div>

Where container queries shine vs. where they don't

• Best for: design system components (cards, list items, form controls) that need to work at multiple sizes across different layout contexts.
• Best for: sidebar layouts where the sidebar width changes based on collapsed/expanded state.
• Worse for: layout primitives (the grid itself, page-level sections) - media queries are still the right tool for anything that reacts to the viewport directly.
• Avoid: deeply nested container queries (querying a container inside a container inside a container) - debugging becomes difficult quickly.

Browser support and the `contain` gotcha

Full browser support is solid, but there's one gotcha: elements with `container-type: inline-size` have implicit `overflow: clip` behavior, which can clip positioned children unexpectedly. If a dropdown or tooltip inside a container-queried element is getting clipped, move the containment context up the tree to a wrapper that doesn't need to show overflow content.

Written by Appesto Engineering.