{"id":400,"date":"2026-06-30T05:04:02","date_gmt":"2026-06-30T05:04:02","guid":{"rendered":"https:\/\/abrarqasim.com\/blog\/tailwind-v4-container-queries-the-media-queries-i-stopped-writing\/"},"modified":"2026-06-30T05:04:02","modified_gmt":"2026-06-30T05:04:02","slug":"tailwind-v4-container-queries-the-media-queries-i-stopped-writing","status":"publish","type":"post","link":"https:\/\/abrarqasim.com\/blog\/tailwind-v4-container-queries-the-media-queries-i-stopped-writing\/","title":{"rendered":"Tailwind v4 Container Queries: The Media Queries I Stopped Writing"},"content":{"rendered":"

I was rebuilding the sidebar on a side project last weekend, and I realized I’d been writing the same useless media query for the last four years. You know the one: lg:flex-row<\/code>, md:grid-cols-2<\/code>, xl:gap-6<\/code>. The component had no idea what page it was on. It just knew the viewport was wide. That’s a different thing, and I’d been pretending it wasn’t for way too long.<\/p>\n

Then I noticed Tailwind v4 had moved container queries out of the plugin and into core. So I deleted about forty lines of breakpoint utilities, dropped a @container<\/code> on the parent, and the component finally started behaving the way I’d been wanting it to since 2021.<\/p>\n

This post is the short version of what changed for me, with the actual code I use now.<\/p>\n

Why viewport breakpoints stopped making sense<\/h2>\n

A media query asks one question: how wide is the browser window. That’s fine when your layout is a single column of full-bleed sections. It falls apart the second you reuse a component in a sidebar, a modal, or a two-up grid.<\/p>\n

I had a <UserCard \/><\/code> that looked great as a full-width hero. Drop it into a 320px sidebar and the avatar wrapped under the name. Drop it into a three-column dashboard and it had too much air. Every time, I’d add another conditional class with a prop like compact<\/code> or variant=\"sidebar\"<\/code>. The component started looking like a switch statement wearing a costume.<\/p>\n

Container queries fix this by letting the component look at its parent, not the window. If the parent is 400px wide, the card lays out horizontally. If the parent is 200px wide, it stacks. The page can put it anywhere and it just works.<\/p>\n

The v4 syntax that finally clicked for me<\/h2>\n

In Tailwind v3 you had to install @tailwindcss\/container-queries<\/code>, register it in your config, and remember which prefix did what. In v4 it’s built in. You mark a container with @container<\/code> and then prefix utilities with @sm:<\/code>, @md:<\/code>, @lg:<\/code> for container-relative breakpoints. Or use arbitrary values like @[400px]:flex-row<\/code> when you want a specific pixel.<\/p>\n

Here’s the before. This is what <UserCard \/><\/code> looked like a month ago, using viewport breakpoints:<\/p>\n

export function UserCard({ user }) {\n  return (\n    <div className="flex flex-col gap-2 md:flex-row md:items-center md:gap-4 lg:gap-6 p-4">\n      <img\n        src={user.avatar}\n        className="w-12 h-12 md:w-16 md:h-16 rounded-full"\n      \/>\n      <div className="flex flex-col">\n        <span className="font-semibold md:text-lg">{user.name}<\/span>\n        <span className="text-sm text-gray-500">{user.role}<\/span>\n      <\/div>\n    <\/div>\n  );\n}\n<\/code><\/pre>\n
Looks reasonable. Breaks instantly the moment you put two of them side by side, because md:<\/code> triggers on viewport width, not the card’s own width.<\/p>\n
And here’s the after, with container queries:<\/p>\n
export function UserCard({ user }) {\n  return (\n    <div className="@container">\n      <div className="flex flex-col gap-2 @sm:flex-row @sm:items-center @sm:gap-4 @md:gap-6 p-4">\n        <img\n          src={user.avatar}\n          className="w-12 h-12 @sm:w-16 @sm:h-16 rounded-full"\n        \/>\n        <div className="flex flex-col">\n          <span className="font-semibold @sm:text-lg">{user.name}<\/span>\n          <span className="text-sm text-gray-500">{user.role}<\/span>\n        <\/div>\n      <\/div>\n    <\/div>\n  );\n}\n<\/code><\/pre>\n
Now it lays out based on the wrapper’s width. Drop it in a 240px sidebar, it stacks. Drop it in a 600px main panel, it goes horizontal. I didn’t have to teach the parent anything.<\/p>\n
The official Tailwind v4 container queries docs<\/a> cover every modifier, but @sm<\/code>, @md<\/code>, and @lg<\/code> plus the arbitrary syntax handle about 90% of what I actually need.<\/p>\n
Where I actually use them in production<\/h2>\n
Three places kept showing up in the last month of work.<\/p>\n
Cards in unknown layouts.<\/strong> Anything I might drop into a Bento-style dashboard. The dashboard owner shouldn’t have to know my component’s preferred width.<\/p>\n
Sidebar widgets.<\/strong> I have a notifications panel that lives in a 320px rail on desktop and goes full-width on mobile (where the rail disappears). Container queries let me write one set of classes that handles both contexts.<\/p>\n
Modal contents.<\/strong> Modals get wider on tablets, narrower on phones, and sometimes a user resizes the window with the modal open. Viewport breakpoints don’t catch a window resize from 1280px to 720px while a 600px modal is open. Container queries do.<\/p>\n
I still use viewport breakpoints for page-level chrome: nav bars, app shells, the marketing landing page where the layout actually does depend on the device. The rule of thumb I’ve settled on is: viewport for layout-of-layouts, container for component internals.<\/p>\n
Named containers, when one parent isn’t enough<\/h2>\n
This is the bit I missed for the first week. By default @sm:<\/code> looks at the nearest @container<\/code> ancestor. If you nest containers, you might want a specific one. Tailwind v4 lets you name them with @container\/sidebar<\/code> and then query against the name with @sm\/sidebar:flex-row<\/code>.<\/p>\n
<aside className="@container\/sidebar w-80">\n  <div className="p-4">\n    <div className="@container\/widget">\n      {\/* This responds to the widget container *\/}\n      <div className="flex flex-col @sm\/widget:flex-row">\n        ...\n      <\/div>\n\n      {\/* And this one explicitly responds to the sidebar *\/}\n      <button className="hidden @sm\/sidebar:inline-block">\n        Expand\n      <\/button>\n    <\/div>\n  <\/div>\n<\/aside>\n<\/code><\/pre>\n
Not something I need every day, but the one time I did need it, I was glad it existed instead of having to compute parent widths in JavaScript like an animal.<\/p>\n
A few sharp edges I hit<\/h2>\n
A couple things tripped me up that I want you to skip.<\/p>\n
First, @container<\/code> only works as a containment context if the element has display<\/code> set to block<\/code>, inline-block<\/code>, or similar. A display: contents<\/code> element won’t work. Tailwind handles this for you if you just slap @container<\/code> on a normal <div><\/code>, but if you’re nesting it on something fancy, double-check the computed styles.<\/p>\n
Second, container queries don’t compose with dark:<\/code> the way I expected. You can chain them as @sm:dark:bg-slate-900<\/code>, but the order matters and I got it wrong twice. The MDN page on CSS container queries<\/a> is the cleanest reference I’ve found for the underlying CSS once you’re past the Tailwind wrapper.<\/p>\n
Third, browser support is fine in 2026 (Chrome, Safari, Firefox all shipped years ago), but if you have telemetry showing a long tail of users on iOS 15, container queries silently fall back to the mobile-first base styles. So write the mobile layout first and treat @sm:<\/code> and up as progressive enhancement. Same discipline you’d use for any CSS feature you can’t polyfill.<\/p>\n
The Chrome team’s web.dev intro to container queries<\/a> is worth a skim if you want the design history of how this got into the platform.<\/p>\n
What I’d do this week if I were you<\/h2>\n
Pick one component you’ve rewritten twice because it kept ending up in different layouts. Wrap its outermost div in @container<\/code>. Replace every md:<\/code> and lg:<\/code> on that component’s internals with @sm:<\/code> and @md:<\/code>. Drop it into two different parent widths in your Storybook (or just two siblings in a test page) and watch it behave.<\/p>\n
If you don’t have a component like that, look at any card or list-item you’ve ever rendered in both a sidebar and a main column. That’s the one.<\/p>\n
One more thing if you’re upgrading from v3. The Tailwind v4 oxide engine post<\/a> I wrote a while back covers what changed in the build pipeline. The container query stuff plays nicely with the new engine, so you don’t need to register anything extra.<\/p>\n
I’ve been ripping container queries into older components for a couple of weeks now. About one in three rewrites lets me delete an entire prop. If you do enough of them, you’ll start designing components that don’t have layout opinions baked in, which is a nicer place to be working from. I cover this kind of thing in my front-end work<\/a> if you want to see it applied to bigger projects.<\/p>\n","protected":false},"excerpt":{"rendered":"
Tailwind v4 ships container queries as first-class utilities. Here’s the @container pattern I now reach for, with before-and-after code from real components.<\/p>\n","protected":false},"author":2,"featured_media":399,"comment_status":"","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"rank_math_title":"","rank_math_description":"Tailwind v4 ships container queries as first-class utilities. Here's the @container pattern I now reach for, with before-and-after code from real components.","rank_math_focus_keyword":"tailwind css v4 features","rank_math_canonical_url":"","rank_math_robots":"","footnotes":""},"categories":[433,35],"tags":[434,37,38,435,139,369,370],"class_list":["post-400","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-tailwind-css","category-web-development","tag-container-queries-2","tag-css","tag-frontend","tag-responsive-design-2","tag-tailwind","tag-tailwind-css-2","tag-tailwind-v4-2"],"_links":{"self":[{"href":"https:\/\/abrarqasim.com\/blog\/wp-json\/wp\/v2\/posts\/400","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/abrarqasim.com\/blog\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/abrarqasim.com\/blog\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/abrarqasim.com\/blog\/wp-json\/wp\/v2\/users\/2"}],"replies":[{"embeddable":true,"href":"https:\/\/abrarqasim.com\/blog\/wp-json\/wp\/v2\/comments?post=400"}],"version-history":[{"count":0,"href":"https:\/\/abrarqasim.com\/blog\/wp-json\/wp\/v2\/posts\/400\/revisions"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/abrarqasim.com\/blog\/wp-json\/wp\/v2\/media\/399"}],"wp:attachment":[{"href":"https:\/\/abrarqasim.com\/blog\/wp-json\/wp\/v2\/media?parent=400"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/abrarqasim.com\/blog\/wp-json\/wp\/v2\/categories?post=400"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/abrarqasim.com\/blog\/wp-json\/wp\/v2\/tags?post=400"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}