For over a decade, CSS media queries have been the bedrock of responsive web design. We have all written the familiar @media (max-width: 768px) { ... } pattern countless times. It works, but it carries a fundamental limitation: it only responds to the viewport size, not the actual space available to a component.
Enter CSS container queries, a revolutionary approach that allows components to adapt based on their parent container's dimensions rather than the entire screen. This shift unlocks unprecedented flexibility for building modular, reusable components that thrive in any context.
Understanding the Core Problem
The traditional media query approach forces developers to assume where a component might appear. A card component designed for a full-width layout will look cramped when dropped into a sidebar. Conversely, a compact sidebar widget appears lost when expanded to a main content area.
Developers have historically solved this with brittle overrides, duplicate classes, or component variants that multiply maintenance overhead. Container queries solve this elegantly by letting the component query its own layout context, making it truly self-aware and adaptable.
Browser Support: Ready for Production
The landscape has shifted dramatically. Container queries are now supported in all major browsers: Chrome/Edge (since 105), Firefox (since 110), and Safari (since 16). With global support exceeding 90%, the feature has graduated from experimental to production-ready.
Progressive enhancement strategies using @supports ensure graceful degradation for legacy browsers, letting you adopt the technique without abandoning older users.
Setting Up Container Query Context
Before querying a container, you must explicitly define which elements serve as query containers. This requires two CSS properties: containment and the container-type declaration.
.card-grid {
container-type: inline-size;
container-name: card-grid;
}The container-type: inline-size line establishes this element as a query container that can be measured against its inline axis width. For most layouts, this is what you need. The optional container-name helps when working with nested containers, letting you target specific ancestors in complex component hierarchies.
Writing Your First Container Query
Once a container is established, child elements can query its dimensions using the @container rule:
.product-card {
display: flex;
flex-direction: column;
}
@container (min-width: 400px) {
.product-card {
flex-direction: row;
align-items: center;
}
.product-card__image {
width: 120px;
height: 120px;
flex-shrink: 0;
}
.product-card__content {
flex: 1;
}
}
@container (min-width: 700px) {
.product-card {
padding: 2rem;
}
.product-card__title {
font-size: 1.5rem;
}
}This product card now automatically switches from vertical to horizontal layout based on the space its parent grants it, not the device screen size. Place it in a narrow sidebar and it stays compact. Drop it in a main content area and it expands gracefully.
Named Containers for Precision
In nested layouts, you may want a component to query a specific ancestor, not just its immediate container. Named containers solve this:
.sidebar {
container-name: sidebar;
container-type: inline-size;
}
.dashboard-widget {
container-name: dashboard;
container-type: inline-size;
}
.calendar-component {
/* Only responds to sidebar width, ignoring dashboard */
display: grid;
grid-template-columns: 1fr;
}
@container sidebar (min-width: 250px) {
.calendar-component {
grid-template-columns: repeat(7, 1fr);
}
}This precision prevents unintended interactions between nested query contexts and makes your component responsive behavior predictable.
Size Queries vs Style Queries
Container queries extend beyond dimensional measurement. Style queries (shipping in 2025) let you query computed style values of a container:
@container style(--theme: dark) {
.adaptive-component {
background: #1a1a1a;
color: #ffffff;
}
}
@container style(--theme: dark) and (min-width: 400px) {
.adaptive-component {
border: 1px solid #333;
}
}This enables sophisticated theming without JavaScript, letting components respond to both their physical space and their stylistic context.
Container Query Length Units
CSS introduces container-relative units that size elements proportionally to their container:
.responsive-text {
/* Scales between 1rem and 3rem based on container width */
font-size: clamp(1rem, 5cqi, 3rem);
}
.adaptive-padding {
/* 4% of container's inline size */
padding: 4cqi;
}Available units include:
cqi: 1% of container's inline size (width in horizontal writing modes)cqb: 1% of container's block size (height in horizontal writing modes)cqw: 1% of container's widthcqh: 1% of container's heightcqminandcqmax: the smaller or larger of cqw/cqh
Real-World Pattern: Responsive Data Tables
Container queries excel at complex UI patterns like data tables that need different presentations at different sizes:
.table-container {
container-type: inline-size;
container-name: data-table;
}
.responsive-table {
width: 100%;
border-collapse: collapse;
}
@container data-table (max-width: 600px) {
.responsive-table thead {
display: none;
}
.responsive-table tr {
display: grid;
grid-template-columns: 1fr 1fr;
gap: 0.5rem;
margin-bottom: 1rem;
border: 1px solid #ddd;
padding: 1rem;
}
.responsive-table td {
display: flex;
justify-content: space-between;
}
.responsive-table td::before {
content: attr(data-label);
font-weight: bold;
}
}Now the same table component intelligently switches from a traditional table view to a card-based layout based on available space, not screen breakpoints that may not correlate with its actual rendered width.
Migration Strategy: From Media Queries
Migrating existing components requires a mindset shift. Instead of viewport breakpoints, identify container thresholds where your component's layout should change. Start with your most reused components: cards, navigation, search forms, and data displays.
Wrap them in explicit container contexts, then gradually replace media queries with container queries. Use @supports to maintain fallback behavior:
.card {
/* Default mobile-first styles */
}
/* Modern browsers: container queries */
@container (min-width: 400px) {
.card {
/* Enhanced layout */
}
}
/* Legacy browsers: media query fallback */
@supports not (container-type: inline-size) {
@media (min-width: 768px) {
.card {
/* Alternative enhanced layout */
}
}
}Integration with Modern CSS Modules
Container queries combine powerfully with other modern CSS modules:
.card-grid {
container-type: inline-size;
display: grid;
gap: 1rem;
/* Subgrid maintains alignment while allowing component flexibility */
grid-template-columns: subgrid;
}
.interactive-card {
/* :has() works with container queries for stateful adaptations */
container-type: inline-size;
}
.interactive-card:has(img) {
/* Card knows it has an image and can adjust layout */
}
@container (min-width: 300px) {
.interactive-card:has(img) {
display: grid;
grid-template-columns: 100px 1fr;
}
}Testing and Debugging
The Computed styles section reveals which container queries currently match. For automated testing, render components inside controlled-width wrappers and assert class presence, visibility, and computed styles at specific container widths.
FAQ
Do container queries replace media queries entirely?
No. Media queries remain valuable for viewport-level changes like navigation breakpoints, overall page layout shifts, and typography scaling. Container queries complement them by handling component responsive behavior. The two work together: media queries for macro layout, container queries for micro layout.
How do container queries affect performance?
The container-type property requires layout containment, which isolates the container from the rest of the document layout. This can actually improve performance by limiting layout recalculation scope. Modern browsers optimize container queries efficiently, so the overhead is minimal even with many query containers on a page.
Can I nest container queries inside each other?
Yes, components can query different ancestor containers at different nesting levels. Use container names to specify which ancestor to query. A nested component might respond to its immediate parent's width while also responding to a distant sidebar container's width for layout decisions, giving you granular control over complex nested interfaces.
