CSS Container Queries in Production - A Year In

CSS container queries allow a component to respond to the size of its own container - not the viewport - making components genuinely composable for the first time. We shipped them across a 200+ component design system in 2023 and ran them in production for a full year. The verdict: strongly positive, but there are things that will catch you off guard if you expect a straight upgrade from media queries.

What Are CSS Container Queries and Why Do They Outperform Media Queries?

CSS container queries allow components to apply styles based on the size of their own containing element rather than the viewport. This is the shift that makes components genuinely composable: a card component can display in its narrow layout when it appears in a three-column grid, and in its wide layout when it appears in a single-column main content area - without the parent component doing anything special and without JavaScript.

Media queries style components based on the viewport width. This works for page-level layouts. It fails for component-level responsiveness, because a component placed in a narrow sidebar at a wide viewport needs small-layout styles, but a media query would tell it the viewport is wide and apply large-layout styles. This has been the responsive CSS problem since media queries were introduced in 2012. Container queries are the solution.

Browser support for container queries reached baseline in 2023: Chrome and Edge 105 (August 2022), Safari 16 (September 2022), and Firefox 110 (February 2023). As of early 2024, global browser support for size-based container queries is above 90% according to Can I Use data. There is no polyfill needed for production use. If your browser support policy covers the last two major versions of Chrome, Safari, and Firefox, container queries are available.

Feature	Chrome/Edge	Safari	Firefox	Status
Size queries (@container)	105+	16+	110+	Baseline - production ready
Named containers (container-name)	105+	16+	110+	Baseline - production ready
Style queries	111+ (flags)	Not supported	Not supported	Experimental - not production ready

The container needs to be established with the container-type property (or the container shorthand). Any element can be a container. The component’s own elements query against the nearest ancestor container using @container.

What Is the Core Benefit of CSS Container Queries Over Media Queries?

Container queries deliver genuinely composable responsiveness. The concrete example: a card component that shows a horizontal layout (image left, text right) when wide, and a vertical layout (image above, text below) when narrow. With media queries, you style the horizontal layout at large viewport widths and the vertical at small. The problem: the same card in a narrow sidebar at a large viewport needs the vertical layout, but the media query tells it to use horizontal.

In our 200+ component library, the components that benefited most from container queries were the ones that appear in multiple layout contexts within the same page: cards (used in full-width content areas, three-column grids, and narrow sidebars), data table cells (varying column widths), stat widgets (full-width hero placement vs sidebar placement), and navigation items (top-level header vs drawer). For these component types, container queries eliminated entire categories of prop-driven layout variants. Instead of <Card variant="narrow"> and <Card variant="wide">, the card adapts based on its container. The API simplifies; the component’s responsibilities become clearer.

The components that did not benefit significantly were those that only ever appear in one layout context (modal headers, for example) and those whose responsiveness was genuinely about viewport size rather than container size (sticky headers, full-screen overlays). Container queries are not a wholesale replacement for media queries - they are a better tool for component-level responsiveness, while media queries remain appropriate for page-level layout.

What Is the container-name Naming Overhead in Shared Libraries?

Every container needs a container-name for named queries. This adds coordination overhead when building a shared library - you need naming conventions so that consuming teams can write queries against named containers without coupling to internal implementation details.

The coordination overhead is real and worth planning for. In a single-team codebase, an unnamed container (container-type: inline-size without a name) is sufficient. Any @container query without a name matches the nearest ancestor container. In a shared component library where consuming teams write their own layout code that wraps your components, unnamed containers can match the wrong ancestor - the consuming team’s container instead of yours. Named containers prevent this.

The naming convention we adopted for the shared library after six months of iteration:

• Component-scoped kebab-case prefix: card-container, stat-widget-container, data-table-container
• No abbreviations: navigation-item-container, not nav-item-ctr
• No generic names: card-container, not container or wrapper or c
• The container name is part of the component’s public API - document it alongside props

The documentation requirement is not optional. In a shared library, container names are as public as prop names. Consuming teams who want to write queries against your components’ containers need to know what names are available. We added container names to the component documentation as a first-class property alongside props in Storybook.

One gotcha that caught several teams in the first month: container-type: inline-size only tracks the inline dimension (width in horizontal writing modes). For components that also need to respond to height, container-type: size is required. But container-type: size creates a formatting context that prevents the element from contributing to its parent’s height calculation - which can cause layout issues in flexbox and grid. Use container-type: size deliberately and document the side effect.

What CSS Container Query Features Are Still Missing?

Size queries are well-supported; style queries are still behind flags in most browsers. When style queries land fully, conditional styling based on CSS custom property values will make theming significantly more powerful.

Style queries would allow this pattern: a container that has --theme: dark set as a CSS custom property could expose that as a queryable state that any descendant component queries against. The component would not need to receive a theme prop - it would query the nearest ancestor container with the --theme custom property and apply dark styles conditionally. This is particularly powerful for theming scenarios where a section of a page runs on a different theme from the rest, and components deep in that section need to adapt without prop drilling or context.

As of early 2026, Chrome 111+ has partial style query support behind a flag. Safari and Firefox have not shipped it. The lack of cross-browser support makes style queries a feature to design for but not ship in production. The practical path: design your components so that CSS custom property-based theming is possible, write the style query version in comments or a future-facing branch, and deploy the fallback implementation (typically a data attribute or class on the container) now. When style queries reach baseline, the fallback can be removed with minimal refactoring.

The decade of workarounds that container queries are making unnecessary includes: wrapper divs added purely to create a breakpoint context, JavaScript ResizeObserver hooks that applied classes based on element width, component variants (Card, CardCompact, CardWide) that existed solely because CSS could not express the responsive logic, and parent-aware prop patterns where a parent component told children their layout context. All of these are symptoms of the same problem - CSS knowing the viewport but not the component’s context. Container queries solve that problem at the right layer.

How Should You Adopt CSS Container Queries in an Existing Codebase?

A staged adoption is lower-risk than a wholesale migration. The approach that worked well in our system:

Stage 1 - New components only. Build all new components with container queries from the start. No migration of existing components yet. This lets the team develop the naming conventions and documentation patterns on low-risk surfaces.

Stage 2 - High-context components. Migrate components that appear in multiple layout contexts and currently use JavaScript resize observers or excessive prop variants. These have the highest return on migration. For each migrated component, run visual regression tests against all known layout contexts.

Stage 3 - Remaining responsive components. Migrate the remaining responsive components on the same schedule as other planned refactors. There is no urgency to migrate components that work correctly with media queries - they are not broken, just suboptimal.

Container queries are production-ready. The browser support question is answered. The only open question is style queries, which affect theming but not core responsive behavior. If you have been waiting on browser support data to justify adopting container queries, that wait is over.

Frequently Asked Questions

Are CSS container queries supported in all major browsers?

Yes. Container size queries reached full support in Chrome/Edge 105 (August 2022), Safari 16 (September 2022), and Firefox 110 (February 2023). Global browser support is above 90%. Style queries - a more advanced feature that queries CSS custom property values - are still experimental and not production-ready across all browsers.

What is the difference between container queries and media queries?

Media queries respond to the viewport dimensions. Container queries respond to the dimensions of a component’s own containing element. This distinction enables component-level responsiveness: a card component can adapt its layout based on whether it is in a narrow sidebar or a wide content area, without the parent needing to pass layout context as a prop. Media queries remain appropriate for page-level layout decisions; container queries are better for component-level responsiveness.

What is container-name in CSS?

container-name is a CSS property that assigns a name to a container, allowing descendant components to query specifically against that named container rather than the nearest ancestor container. In shared libraries, naming containers is essential to prevent consuming teams’ wrapper elements from accidentally matching component queries. Container names should be treated as part of the component’s public API and documented alongside props.

When should I use container queries instead of media queries?

Use container queries when a component needs to adapt its layout based on its own available space, particularly when the same component appears in multiple layout contexts (sidebar, main content, full-width, modal). Use media queries for page-level layout decisions where the viewport dimensions are genuinely the relevant variable. Many responsive designs benefit from both: media queries handling the page grid and container queries handling individual component adaptation.

Are CSS style queries supported in production?

Not yet. Style queries (querying CSS custom property values on a container) have partial support in Chrome 111+ behind flags, and no support in Safari or Firefox as of early 2026. They are not production-ready. The correct approach is to design components so CSS custom property-based theming is architecturally possible, deploy a class or data attribute fallback today, and migrate to style queries when they reach cross-browser baseline.