Container queries are the biggest shift in responsive design since media queries were introduced. They are now baseline — supported in Chrome 105+, Firefox 110+, Safari 16+, and Edge 105+, covering over 93% of global browser usage. They are safe for production.
Yet most developers still default to media queries, because the tutorial content available explains what container queries are without showing when and how to use them on real components. MDN has the reference. web.dev has the foundational explainer. CSS-Tricks has an introduction from 2023. But none provide the production-ready component patterns that developers need to start using container queries today.
This guide provides three real-world component examples with full code — a responsive product card, an adaptive sidebar, and a resizable dashboard widget — plus the decision framework for when to use container queries versus media queries.
The mental model in 30 seconds
Media queries ask: "How wide is the browser viewport?"
Container queries ask: "How wide is this component's parent container?"
That distinction changes how you think about responsive components. A card component built with media queries breaks when you move it from a wide content area to a narrow sidebar — it responds to the viewport width, which hasn't changed, even though its available space shrank dramatically. The same card built with container queries adapts automatically — it responds to its own container's width.
The syntax
That is the complete mental model. Declare a container. Query its size. Adjust the child layout. Everything else is application of this pattern to different components and contexts.
Example 1 — the responsive product card
The most common container query use case: a card that stacks vertically in narrow containers and goes horizontal in wider ones.
Why this matters: This same card works in a 3-column grid, a 2-column grid, a sidebar, a modal, or a full-width layout — without any CSS changes. The card adapts to wherever you place it because it queries its container, not the viewport.
With media queries, you would need different CSS rules for each layout context. With container queries, the component is self-contained and portable.
<!-- IMAGE: Side-by-side showing the same card component in a wide grid (horizontal layout), a sidebar (stacked layout), and a mobile view — all from the same CSS using container queries. Alt text: "Product card component adapting to three different container widths using CSS container queries — horizontal in wide grid, stacked in sidebar." Host on mantlr.com/blog/images/ -->
Example 2 — the adaptive sidebar navigation
Sidebars are the killer use case for container queries. Their width changes independently of the viewport — when a user collapses the sidebar, resizes a panel, or when the layout reconfigures between views.
No JavaScript toggling a isCollapsed class. No state management for sidebar width. The navigation adapts purely based on available space. Drag the sidebar wider — labels appear. Narrow it — labels disappear and icons center. The transition feels fluid and intentional.
Example 3 — the dashboard widget
Dashboard widgets live in resizable grid cells. Their content needs to adapt to whatever space the user or layout assigns them — compact number display in small cells, full charts in large ones.
Notice the clamp(1.25rem, 5cqi, 2rem) on the value — that uses container query units (cqi = container query inline size). The number scales with the widget's container width, clamped between minimum and maximum values. No breakpoints needed for that specific sizing — it scales fluidly.
This pattern makes dashboard design dramatically simpler. Each widget is self-contained. It does not know or care whether it is in a 2-column or 6-column grid.
Container queries vs media queries — when to use which
Container queries do not replace media queries. They solve different problems.
Use container queries when:
- You are building reusable components that appear in multiple layout contexts
- A component might live in both a sidebar AND a main content area
- Dashboard widgets need to adapt to resizable grid cells
- A component's responsive behavior should travel with the component, not be defined by the page layout
Use media queries when:
- You are making page-level layout decisions (switching from sidebar to bottom navigation on mobile)
- You need to adjust global typography scale between mobile and desktop
- You are showing or hiding entire page sections based on screen size
- The responsive change is about the page, not an individual component
The practical rule: If the responsive behavior belongs to a specific component, use container queries. If the responsive behavior belongs to the page layout, use media queries. Most real-world projects need both.
Container query units for responsive typography
Container queries introduce units relative to the container: cqw (width), cqh (height), cqi (inline size), cqb (block size).
These enable responsive typography without viewport units:
Text scales with the container width — not the viewport. A card in a narrow sidebar gets smaller text. The same card in a wide content area gets larger text. No breakpoints, no classes — just fluid scaling tied to the component's context.
Using container queries with Tailwind CSS
Tailwind v3.4+ includes native container query support via the @container utility:
The @container parent declares containment. @md: and @lg: prefixes work like responsive breakpoints but query the container, not the viewport. Tailwind v4 extends this support further.
Browser support and progressive enhancement
Container queries are baseline since late 2023. Current global support exceeds 93%. For the rare cases requiring older browser support, container queries degrade gracefully — the default (mobile-first) styles apply, and the container-responsive enhancements simply do not activate.
Nothing breaks. Older browsers get the stacked layout. Modern browsers get the adaptive layout.
Frequently asked questions
What are CSS container queries?
Container queries let you style elements based on their parent container's size rather than the browser viewport. A card component can display differently in a sidebar versus a main content area without any JavaScript or viewport-dependent media queries — it responds to its own available space.
When should I use container queries instead of media queries?
Use container queries for component-level responsive design — reusable elements that appear in different layout contexts. Use media queries for page-level layout changes. If the question is "should this card change layout based on where it is placed?" use container queries. If the question is "should the page switch from sidebar to bottom nav?" use media queries.
Are CSS container queries supported in all browsers in 2026?
Yes. Chrome 105+, Firefox 110+, Safari 16+, and Edge 105+ all support container queries. Global support exceeds 93%. They are production-safe.
Can I use container queries with Tailwind CSS?
Yes. Tailwind v3.4+ includes @container utilities. Add @container to a parent element and use @sm:, @md:, @lg: prefixes on children to create container-responsive layouts. Tailwind v4 extends this support with additional container query features.
What are container query units (cqw, cqi)?
Container query units are relative to the queried container's dimensions: cqw (1% of container width), cqh (1% of container height), cqi (inline size), cqb (block size). Use them for fluid sizing — like font sizes that scale with the container rather than the viewport.
How do container queries affect performance?
Container queries have minimal performance impact. The browser evaluates containment contexts efficiently, similar to how it evaluates media queries. The container-type: inline-size declaration does create a new formatting context, which means the browser must calculate the container's size before styling its children — but this overhead is negligible in practice.
[Explore CSS tools, layout resources, and frontend development guides → Mantlr](https://mantlr.com)
Written by [Author Name], a product designer building [Mantlr](https://mantlr.com) — a curated resource directory for designers and developers.