How CSS Container Queries Make Components Responsive
You build a product card that looks right in the main column, then someone drops the same card into a 300 pixel sidebar and the layout falls apart.

You build a product card that looks right in the main column, then someone drops the same card into a 300 pixel sidebar and the layout falls apart. Media queries cannot help, because the viewport is still 1,400 pixels wide and the card has no idea it has been squeezed. CSS container queries fix exactly this problem by letting a component respond to the space it is given rather than the size of the whole screen.
This article covers how container queries work, how to set them up step by step, the units that come with them, and when a media query is still the better tool.
The problem CSS container queries solve
For years, responsive design meant media queries. You wrote rules like "at widths above 768 pixels, show the card image beside the text". That works when a component always spans the full page width. It breaks the moment the same component appears in a grid with three columns, a sidebar, or a modal, because each placement gives it a different width on the same screen.
The usual workaround was a stack of modifier classes: card, card-compact, card-sidebar, card-wide. Every new placement meant a new class and someone remembering to apply it. Container queries remove that bookkeeping. The card measures its own container and picks its layout, so one set of styles works everywhere.
Setting up a container query step by step
There are two parts: declare a container, then write rules that query it.
1. Declare the container
On the element that wraps your component, set container-type: inline-size. The word inline refers to the inline axis, which is width in a normal left to right page. You can also name the container with container-name: card, or use the shorthand container: card / inline-size.
The container must be a parent of the elements you want to style. An element cannot query its own size, because changing its styles could change its size and create a loop. That rule is the source of most first attempts that seem to do nothing.
2. Write the query
Inside your stylesheet, use an @container rule with a size condition, such as @container card (min-width: 400px). Inside it, put the styles for the wider layout, for example switching the card to a two column grid with the image on the left. Without a name, the rule matches the nearest ancestor that is a container.
3. Test in several placements
Put the component in at least three places with different widths and resize the browser. In Chrome and Firefox DevTools, elements that are containers show a badge in the Elements panel, and selecting it highlights the container box so you can see which width the query is reading.
Container query units
Container queries come with their own length units, and they are often more useful than the queries themselves:
- cqi is 1 percent of the container's inline size, usually its width.
- cqb is 1 percent of the container's block size, usually its height.
- cqmin and cqmax use the smaller or larger of the two.
A practical use is fluid type inside a component. Setting a heading to font-size: clamp(1rem, 5cqi, 1.75rem) makes it scale with the card instead of the viewport, while clamp keeps it readable at both ends. A card heading in a narrow sidebar stays small, and the same heading in a wide feature slot grows, with no extra breakpoints.
When media queries are still the right choice
Here is the counter-take. Since container queries arrived, some developers have started to treat media queries as outdated and convert everything. I think that is a mistake, and it makes stylesheets harder to follow.
Page level layout should still use media queries. Whether the navigation collapses into a menu button, whether the page has one column or three, and whether the sidebar appears at all are decisions about the screen and the device, not about a component. Media queries also handle things containers cannot see, such as prefers-reduced-motion, prefers-color-scheme, hover capability and print styles.
A good split is: media queries shape the page, container queries shape the pieces. If you find yourself declaring the body or main element as a container just to avoid writing a media query, step back. You have rebuilt a media query with more moving parts.
Performance and browser support
Container queries are supported in all current major browsers, including Chrome, Edge, Firefox and Safari, and have been for over three years. For most public sites you can use them without a fallback. If you need to support older browsers, write the narrow layout as the default and add the wider layout inside the @container rule, so older browsers simply get the compact version.
On performance, declaring a container applies size containment on that axis, which tells the browser the element's size does not depend on its children. That is usually cheap. The cost to watch is declaring hundreds of nested containers in a long list. Put the container on the list item wrapper or on a section, not on every tiny element inside.
Container queries also pair well with other modern CSS features. If your stylesheet is growing, organising component rules with CSS cascade layers keeps container rules from fighting with base styles. Our overview of what modern CSS can do now that used to need JavaScript covers related features such as :has() and native nesting.
A real example: a product card in three places
On a recent project, one product card appeared in a four column grid, a two column related products row and a 280 pixel cart sidebar. With media queries, it needed three modifier classes and about 90 lines of overrides. With one container on each placement wrapper and two @container rules at 360 and 560 pixels, the overrides dropped to about 30 lines and the modifier classes disappeared. New placements since then have needed zero extra CSS.
The images inside those cards still needed correct sizing hints, since container queries do not change how the browser picks an image source. The sizes attribute, explained in responsive images and the sizes attribute, is still based on the viewport.
Frequently asked questions
What is the difference between container queries and media queries?
Media queries respond to the viewport or device, such as screen width or user preferences. Container queries respond to the size of a specific parent element. Use media queries for page layout and container queries for reusable components.
Why is my CSS container query not working?
The most common cause is a missing container-type on a parent element, or trying to style the container itself instead of its children. Also check that the container has a width that actually changes. A container with a fixed width will never cross your breakpoint.
Can container queries check height?
Yes, if you set container-type: size instead of inline-size. This needs the container to have an explicit height, otherwise containment can collapse it to zero. Most layouts only need width, so inline-size is the safer default.
More in Front-End
Front-End
How to Find the Element Causing Horizontal Scroll
A tester filed a bug last March that said "page wobbles sideways on my phone". No screenshot, no device model.
Front-End
How Front-End Retry Code Quietly Overloads Your API
A payments endpoint we run went dark for about 90 seconds on a Tuesday afternoon.
Front-End
Why z-index Stops Working: Stacking Contexts Explained
The dropdown menu opens, and half of it disappears behind the hero image below. You give the menu z-index: 10 . Nothing.