{"id":147,"date":"2026-04-24T13:02:55","date_gmt":"2026-04-24T13:02:55","guid":{"rendered":"https:\/\/abrarqasim.com\/blog\/tailwind-container-queries-i-finally-get-it\/"},"modified":"2026-04-24T13:02:55","modified_gmt":"2026-04-24T13:02:55","slug":"tailwind-container-queries-i-finally-get-it","status":"publish","type":"post","link":"https:\/\/abrarqasim.com\/blog\/tailwind-container-queries-i-finally-get-it\/","title":{"rendered":"Tailwind Container Queries: The One Feature I Wish I’d Used Sooner"},"content":{"rendered":"

Confession: I spent two years telling myself container queries were a “nice to have” and kept shipping media-query hacks instead. Then last month a sidebar-width card component finally forced my hand, and within an afternoon I was quietly rewriting four older components to use them. If you’ve also been squinting at the docs and thinking “yeah I’ll get to it,” this post is for you.<\/p>\n

I’m going to walk through the exact before\/after code, when I reach for @container<\/code> vs a media query, and the one footgun that tripped me up for a solid hour. No theory lecture. Just the stuff I actually needed.<\/p>\n

What container queries actually solve<\/h2>\n

The problem: a card component has no idea how wide its parent is. You might drop the same card into a full-width hero slot on one page and a narrow sidebar on another. Media queries only see the viewport, so the card’s layout responds to the wrong thing.<\/p>\n

Media queries say “when the screen is 768px wide.” Container queries say “when this container<\/em> is 400px wide.” That’s the whole idea. The browser-level feature landed in stable Chrome, Safari, and Firefox back in 2023, and coverage is now sitting above 93% globally if you check caniuse for container queries<\/a>. I stopped worrying about the fallback question somewhere last year.<\/p>\n

Tailwind shipped first-class support for them in v4 as a core plugin. In v3 you needed @tailwindcss\/container-queries<\/code> installed separately; in v4 it’s baked in, so you get the @container<\/code> directive and the @sm:<\/code>, @md:<\/code>, @lg:<\/code> variants with no extra config. The official Tailwind docs on container queries<\/a> are actually pretty good now, which wasn’t always true.<\/p>\n

The before code I’m mildly embarrassed about<\/h2>\n

Here’s the card I had in three places across a dashboard, with viewport-based responsive classes that looked fine on the homepage and broke in a sidebar:<\/p>\n

\/\/ before: card that lies to itself about its width\nexport function StatCard({ label, value, trend }) {\n  return (\n    <div className="rounded-2xl border p-4 md:p-6 lg:p-8">\n      <div className="flex flex-col md:flex-row md:items-center md:justify-between gap-2">\n        <p className="text-sm text-gray-500">{label}<\/p>\n        <p className="text-2xl md:text-3xl lg:text-4xl font-semibold">{value}<\/p>\n      <\/div>\n      <p className="mt-2 text-xs text-gray-400">{trend}<\/p>\n    <\/div>\n  );\n}\n<\/code><\/pre>\n
Drop that card into a 280px sidebar at desktop width and you get the md:flex-row<\/code> layout squashed into a tiny column, with a 3xl font sitting above a ten-character value. The card doesn’t know it’s small. The viewport is wide, so Tailwind happily applies the big-screen classes.<\/p>\n
The hack I used to get around this was passing in a size=\"sm\"<\/code> prop and branching on it. That scales badly. Three callsites turn into ten, and now the card component has to know about every layout it might land in.<\/p>\n
The after code, with @container doing the work<\/h2>\n
Same component, rewritten to respond to its own width instead of the viewport:<\/p>\n
\/\/ after: card that reads its own container\nexport function StatCard({ label, value, trend }) {\n  return (\n    <div className="@container rounded-2xl border p-4 @md:p-6 @lg:p-8">\n      <div className="flex flex-col @md:flex-row @md:items-center @md:justify-between gap-2">\n        <p className="text-sm text-gray-500">{label}<\/p>\n        <p className="text-2xl @md:text-3xl @lg:text-4xl font-semibold">{value}<\/p>\n      <\/div>\n      <p className="mt-2 text-xs text-gray-400">{trend}<\/p>\n    <\/div>\n  );\n}\n<\/code><\/pre>\n
Two changes. I added @container<\/code> to the outer div, which tells the browser “measure this element and use its width for any @<\/code> variant children.” Then I swapped every md:<\/code> for @md:<\/code>. That’s it. Now when the card lands in the sidebar, the flex-column layout stays. When it lands in a hero slot, the flex-row layout kicks in. The card stopped lying to itself.<\/p>\n
The @md<\/code> breakpoint in Tailwind v4 is 448px of container width by default, not viewport. @sm<\/code> is 384px, @lg<\/code> is 512px, @xl<\/code> is 576px. You can find the full table in the Tailwind v4 container query reference<\/a>, and you can override the scale if your design system uses different breakpoints.<\/p>\n
The footgun that cost me an hour<\/h2>\n
Here’s the thing nobody tells you: the element with @container<\/code> on it cannot<\/strong> also use its own @md:<\/code> classes. Container queries don’t self-reference. So this looks reasonable but does absolutely nothing:<\/p>\n
<div class="@container @md:flex-row flex-col">\n  ...\n<\/div>\n<\/code><\/pre>\n
The @md:flex-row<\/code> won’t fire even when the div is wide, because the div is its own container, and the container’s width at query time is measured from the child’s perspective<\/em>. The div isn’t a child of itself.<\/p>\n
Fix: wrap it. Put @container<\/code> on the outer element, and put the @md:<\/code> classes on the inner content. I lost a solid hour to this the first time, staring at the DevTools and wondering why my selector was never matching.<\/p>\n
When I reach for media queries instead<\/h2>\n
Container queries are not a full replacement. I still use viewport media queries for:<\/p>\n