Build a dashboard card component with the standard three breakpoints, mobile, tablet, desktop. Then someone drops that exact card into a narrow sidebar widget, and it breaks instantly. Text overflows, the icon overlaps the label, the whole thing looks like a bug report screenshot. The viewport is desktop-sized. The card just isn't.
That's the blind spot in fixed breakpoint thinking: it assumes a component's context matches the browser window. It rarely does anymore, not with dashboards, CMS blocks, and widgets that get dropped into wildly different layouts on the same page.
TL;DR: Fixed viewport breakpoints can't see a component's rendered width. Container queries can, and size queries have been Baseline since February 2023 (Chrome 105, Firefox 110, Safari 16, per MDN). In the State of CSS 2025 survey they ranked third among the features respondents named as their favorite new CSS of the year.
Why Do Fixed Breakpoints Keep Breaking on Real Projects?
Because a fixed breakpoint asks the wrong question. It asks "how wide is the browser window?" when the question that actually matters is "how wide is this specific component right now?" A card in a full-width hero section and the same card in a 280px sidebar live at completely different effective widths, on the exact same device, in the exact same browser session. Mobile-first design solved the small-screen-up ordering problem years ago. It never solved the reusable-component problem, because that problem didn't really exist until component libraries and CMS-driven layouts became the default way teams build.
The usual workaround before native support was JavaScript: a resize observer measuring each element and toggling classes based on its width. It works. It also adds layout thrash risk and means every component carries its own bespoke measurement logic. Nobody wants to maintain that at scale.
What Do Container Queries Actually Fix?
Container queries let a component respond to the width of its containing element instead of the viewport. You mark a wrapper with container-type: inline-size, name it if you want to target it specifically, then write @container rules that fire based on that container's rendered width.
.card-wrapper {
container-type: inline-size;
container-name: card;
}
@container card (min-width: 320px) {
.card {
display: grid;
grid-template-columns: 96px 1fr;
}
}
@container card (max-width: 319px) {
.card {
display: flex;
flex-direction: column;
}
}
Drop that same .card into a sidebar, a modal, or a full grid column, and it adapts on its own. No JavaScript, no per-page overrides, one rule that travels with the component wherever it gets used.
A component that only knows the viewport width is guessing. A component that knows its own width is designed.
| Media queries | Container queries | |
|---|---|---|
| Responds to | Browser viewport | Containing element's width |
| Owns | Page-level layout shape, sidebar presence | Component-level adaptation |
| Best for | Overall structure | Reusable components (cards, nav items, form rows) |
What Does container-type Actually Do to an Element?
More than labeling a wrapper. The property takes normal, size or inline-size, and each one switches on a kind of containment. MDN's page for container-type says inline-size applies style and inline-size containment, so the element's inline size "can be computed in isolation, ignoring the child elements." Plain size does the same for both axes.
That has a consequence people trip over. Size containment, in MDN's words, "turns off the ability of an element to get size information from its contents," so the container's size has to come from context: a block-level element stretching to its parent, or an explicit value. Without one, the element collapses. The same logic applies along the inline axis. Put container-type: inline-size on a shrink-to-fit wrapper, such as an inline-block or a float, and there's no width left for it to derive from its children.
It's also why inline-size is the default choice. Querying height needs size, and a container with size containment needs an explicit height or it collapses to nothing. Most components only care about width anyway.
Two more rules from the MDN guide are worth keeping close:
- An element is never its own container. A query matches the nearest ancestor with a containment context, so the
@containerrules style descendants. That's why the wrapper and the.cardin the code above are two elements. - Names filter, nesting combines. An unnamed query uses the nearest ancestor with a matching container type. A named one (
container-name: card, or the shorthandcontainer: card / inline-size) skips unrelated containers in between. A single query can't target two containers at once, so nest one@containerinside another.
Should You Rewrite Your Whole Breakpoint System Right Now?
No. Media queries still do the job at the page level, layout shape, navigation pattern (the mobile navigation patterns guide covers the tab-bar versus drawer call), whether a sidebar exists at all. Rip those out and replace them with container queries and you've made your codebase harder to reason about for no real gain. The right split is boring: page-level structural decisions stay in media queries, component-level adaptation moves to container queries. A sensible migration order is the three or four most-reused components first, cards, navigation items, form rows, with everything else left alone until there's a real reason to touch it.
How Do You Actually Plan a Breakpoint Strategy for a New Project?
Start at the page level with four viewport breakpoints, not eleven. Mobile at 375px, tablet at 768px, desktop at 1280px, and an optional wide catch above 1920px if your audience actually has ultra-wide monitors, check your analytics before you assume they do. That's the outer frame. Then, for anything that gets reused, a card, a stat block, or the tiers of a pricing page layout, wrap it in a container and let it manage its own internal layout with @container rules.
If you're building the numeric side of this, our free spacing scale generator produces a consistent token set for gaps and padding that holds up across both breakpoint types, so your container-query components and your page-level layout share the same rhythm instead of drifting apart. Container query length units let font sizes and padding scale with the container too, which pairs naturally with the fluid typography clamp() approach most modern sites already use for page-level type. To see the resulting clamp() curve before you commit numbers, the clamp preview tool above plots min, preferred and max across every viewport width.
Which Units and Syntax Make Container Queries Easier to Write?
Two small additions do most of the work once the basic query feels familiar.
The first is the family of container query length units. cqw and cqh are 1% of the container's width and height, cqi and cqb are 1% of its inline and block size, and cqmin and cqmax take the smaller or larger of the pair. If no eligible container exists, MDN notes that they fall back to the small viewport unit for that axis, so a component rendered outside any container degrades to something sensible instead of to zero.
The second is range syntax. The min-width: 320px and max-width: 319px pair in the first example works, but it needs that awkward 319. Comparison operators say the same thing without it: (width >= 320px), or a bounded band such as (320px <= width < 480px). MDN lists =, <, <=, > and >= for size queries, and the same operators work in @media.
.card h3 {
font-size: clamp(0.9375rem, 5cqi, 1.375rem);
}
@container card (width >= 440px) {
.card {
padding-inline: 20px;
}
}
The title above scales at 5% of the container's inline size, clamped between 15px and 22px, and the padding widens once the container reaches 440px. Both rules run in the preview at the top of this article, so drag the slider and watch the numbers move with the container instead of the window.
How Do You Test a Component That Responds to Its Container?
Resizing the browser window proves very little, because the window isn't what the component is listening to. Render the component inside fixed-width wrappers instead and test either side of every threshold. For the card above that means 319px and 320px, since the pair of queries flips exactly there, and then a width on each side of the 440px padding step. The slider in the preview does this by hand; a story or a test fixture per width does it permanently. Finish with the page-level check from the next sections: the whole layout at 320px wide, and again with the browser zoomed to 400 percent.
Which Container Query Features Can You Ship Today?
"Container queries" now covers three different things, and they don't share a support story. The figures below come from the browser compatibility data behind MDN's @container page, checked on 2026-10-16. Edge follows Chrome.
| Feature | Chrome | Firefox | Safari | Status |
|---|---|---|---|---|
Size queries (width, inline-size) | 105 | 110 | 16 | Baseline widely available since February 2023 |
| Style queries on custom properties | 111 | 151 | 18 | All three engines; Firefox since 2026-05-19 |
| Scroll-state queries | 133 | not supported | not supported | Experimental |
Size queries are the safe default. Style queries let a component react to a custom property set on an ancestor, for example @container style(--density: compact), and they're now in all three engines. Two details from MDN matter in practice: a custom property holding blue won't match a query for #0000ff unless the property is registered with @property as a color, and in Safari the document element can't be a container. Scroll-state queries (stuck, snapped, scrollable) are Chrome-only, so keep them behind progressive enhancement.
How much did the wait for Firefox matter? State of CSS 2025 gives a clue. Style queries drew 26 answers in the list of features respondents avoid or struggle with because of browser support, up 11 places from the previous year, while size queries drew 22. Older opinions about style queries are worth rechecking against the table above.
What Should Media Queries Still Handle?
Anything about the person and the device rather than the box. A container can't tell you how someone points at the screen.
pointerreports the accuracy of the primary input:finefor a mouse,coarsefor something like a finger,nonewhen there's no pointing device. MDN stresses that it describes the primary input only, and thatany-pointertests every available one. Use it to enlarge hit areas on touch.hovertells you whether the primary input can hover conveniently. Gate hover-only reveals behind(hover: hover)and give everyone else a tap path.prefers-reduced-motionreports a system setting to minimize non-essential motion. Animations that run when a card re-flows belong behind it.
All three have been available across browsers for years (MDN dates pointer and hover to December 2018 and prefers-reduced-motion to January 2020).
There's also a floor that no layout strategy gets to ignore. WCAG 2.2 Success Criterion 1.4.10, Reflow, at level AA, asks that content be presentable without two-dimensional scrolling at a width of 320 CSS pixels. W3C's Understanding page notes that 320 CSS pixels equals a 1280px-wide viewport zoomed to 400%. Data tables are among the listed exceptions. So test every layout at 320px wide, whatever mix of media and container queries produced it.
How Do Tailwind's Container Variants Compare to Viewport Breakpoints?
If a team already writes utility classes, the mapping is direct. Per the current Tailwind docs, @container marks an element as an inline-size container, and variants like @md: apply at that container size and up. @max-md: flips it, and @container/main with @sm/main: targets a named one.
The detail worth noticing is that the two scales aren't the same size.
| Step | Container variant starts at | Viewport variant starts at |
|---|---|---|
| xs | 20rem (320px) | not defined |
| sm | 24rem (384px) | 40rem (640px) |
| md | 28rem (448px) | 48rem (768px) |
| lg | 32rem (512px) | 64rem (1024px) |
A component that wants to switch layouts at 384px of its own width should use @sm. Using the viewport sm would fire at 640px, which is a different decision. Notice, too, that the 320px threshold in the card example at the top is Tailwind's @xs. Component thresholds sit lower than page thresholds because components are narrower than pages, which is the whole argument for having two systems.
Fixed breakpoints aren't dead, they're just no longer the whole strategy. Treat the viewport and the component as two separate, related problems, and stop trying to solve both with one set of numbers.
Run the numbers yourself
A component that knows its own width still needs sizes that move smoothly between its breakpoints, and clamp() is the other half of that answer. Enter a minimum, a preferred and a maximum below, then drag the viewport slider to see where the curve flattens.