CSS Container Queries: Replace Media Queries for Component-Level Responsiveness

Container queries let components respond to their parent container's size instead of the browser viewport. After years as a CSS wishlist item, they're now at 97% browser support and ready for production use. This guide shows where they shine and how to migrate from media queries.

The problem with media queries for components

Media queries work on the viewport. A card component that should be 2-column at wide widths and 1-column at narrow widths can't know its own width from a media query — it only knows the viewport width.

This creates the "sidebar problem": a card that looks perfect in a 3-column grid (viewport 800px) breaks when the same component is placed in a sidebar (viewport still 800px, but the card is only 250px wide).

Container queries syntax

First, establish a containment context on the parent:

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

Then, query the container width in the child:

@container (min-width: 400px) { .card { display: grid; grid-template-columns: 1fr 1fr; } }

The @container rule fires when the nearest ancestor with container-type is at least 400px wide — regardless of viewport size.

Named containers

If you have nested containers, name them to query a specific one:

.sidebar { container: sidebar / inline-size; } @container sidebar (min-width: 300px) { .widget { ... } }

container-type values

Use inline-size for the vast majority of cases. size creates a strong containment that can break height-based layouts.

Style queries

Container style queries (now in Chrome and Safari) allow querying CSS custom property values:

.theme-container { --variant: primary; } @container style(--variant: primary) { .button { background: blue; } }

This enables component variants without additional class names or JavaScript.

When to use container queries vs media queries

• Use container queries for component-level responsiveness — cards, sidebars, widgets that can be placed anywhere in the layout.
• Use media queries for page-level responsiveness — navigation changes, grid breakpoints that depend on the overall viewport size, print styles.
• Container queries are not a replacement for media queries — they're complementary. Most responsive designs benefit from both.

Migrating an existing component

Before (media query):

@media (min-width: 768px) { .product-card { grid-template-columns: 200px 1fr; } }

After (container query):

.product-card-wrapper { container-type: inline-size; } @container (min-width: 400px) { .product-card { grid-template-columns: 200px 1fr; } }

The component now works correctly whether it's 400px wide in a full-width layout or 400px wide in a sidebar.

Browser support

Container queries (size and inline-size) are supported in Chrome 105+, Firefox 110+, Safari 16+ — covering 97%+ of browsers in 2026. You can use them in production without a JavaScript polyfill.