{"id":264,"date":"2026-05-22T05:01:42","date_gmt":"2026-05-22T05:01:42","guid":{"rendered":"https:\/\/abrarqasim.com\/blog\/tailwind-v4-container-queries-i-stopped-faking-responsiveness\/"},"modified":"2026-05-22T05:01:42","modified_gmt":"2026-05-22T05:01:42","slug":"tailwind-v4-container-queries-i-stopped-faking-responsiveness","status":"publish","type":"post","link":"https:\/\/abrarqasim.com\/blog\/tailwind-v4-container-queries-i-stopped-faking-responsiveness\/","title":{"rendered":"Tailwind v4 Container Queries: I Stopped Faking Responsiveness"},"content":{"rendered":"

Short version for the impatient: if you’re on Tailwind v4 and you’re still writing md:flex-row<\/code> on a component that lives inside a sidebar, you’re styling the wrong thing. Container queries fixed a class of bugs I’d been working around for years. If you want to know why, read on.<\/p>\n

I rebuilt the same product card four times last year. Not because the design changed. Because the card kept ending up in places I hadn’t planned for: a wide hero grid, a narrow sidebar list, a half-width modal. Every time, the breakpoints I’d written for the viewport made the card look slightly broken in at least one of those places. I’d add another modifier, ship it, and tell myself the next refactor would be cleaner.<\/p>\n

It wasn’t, because I was solving the wrong problem. The viewport is not what’s wrong with a card in a sidebar. The sidebar is what’s wrong with a card in a sidebar. Container queries let you write CSS that knows about the actual container the component is sitting in, not the window the user happens to have open. Tailwind v4 makes the syntax pleasant enough that I now use them by default for anything I expect to compose into more than one layout.<\/p>\n

What media queries were always lying to me about<\/h2>\n

The original responsive design contract was: tell me how wide the viewport is and I’ll tell you how big things should be. That worked when pages had one column and a header. It stopped working the moment we built design systems out of components that get reused at different sizes.<\/p>\n

Here’s the kind of code I used to write in Tailwind v3:<\/p>\n

\/\/ Card.jsx \u2014 Tailwind v3\nfunction ProductCard({ product }) {\n  return (\n    <article className="flex flex-col gap-4 rounded-2xl border p-4 md:flex-row md:items-center md:gap-6 lg:p-6">\n      <img\n        src={product.image}\n        alt=""\n        className="aspect-square w-full rounded-xl md:w-40 lg:w-48"\n      \/>\n      <div className="flex flex-col gap-2 md:flex-1">\n        <h3 className="text-lg font-semibold md:text-xl">{product.name}<\/h3>\n        <p className="text-sm text-slate-600">{product.summary}<\/p>\n        <span className="text-base font-medium">${product.price}<\/span>\n      <\/div>\n    <\/article>\n  );\n}\n<\/code><\/pre>\n
It looks fine. It even works fine on the page I built it for. The problem starts the day I drop the same card into a 320px-wide sidebar on a wide monitor. The viewport is over md<\/code>, so the card goes horizontal, the image gets pinned at w-40<\/code>, and the title squishes next to a thumbnail that takes up half the available space.<\/p>\n
The viewport is screaming “you’re on a desktop, do desktop things.” The card has no idea it’s stuck in a 320px box. I used to fix this with prop drilling: pass a variant=\"compact\"<\/code> flag down so the card could override its own breakpoints. That works, sort of, until you’re four levels deep and the variant flag is on a third of your components for no good reason.<\/p>\n
What Tailwind v4 actually gives you<\/h2>\n
Container queries shipped to all evergreen browsers a while back. The CSS itself looks like this:<\/p>\n
.card-container {\n  container-type: inline-size;\n}\n\n@container (min-width: 480px) {\n  .card { display: flex; flex-direction: row; }\n}\n<\/code><\/pre>\n
Tailwind has had @tailwindcss\/container-queries<\/code> as a plugin since v3.2 if you wanted them. The friction was real though: install plugin, configure it, then write @md:flex-row<\/code> and remember to mark a parent as @container<\/code>. People didn’t reach for it casually.<\/p>\n
In v4 the plugin moved into core. The Tailwind v4 release notes<\/a> call it out as one of the built-in capabilities you get without a plugin. The full container query reference lives in the responsive design docs<\/a>, including the @container<\/code> utility and the @sm<\/code>, @md<\/code>, @lg<\/code> size variants that match container width instead of viewport width.<\/p>\n
Here’s the same card rewritten so it cares about its own container:<\/p>\n
\/\/ Card.jsx \u2014 Tailwind v4\nfunction ProductCard({ product }) {\n  return (\n    <article className="@container">\n      <div className="flex flex-col gap-4 rounded-2xl border p-4 @md:flex-row @md:items-center @md:gap-6 @lg:p-6">\n        <img\n          src={product.image}\n          alt=""\n          className="aspect-square w-full rounded-xl @md:w-40 @lg:w-48"\n        \/>\n        <div className="flex flex-col gap-2 @md:flex-1">\n          <h3 className="text-lg font-semibold @md:text-xl">{product.name}<\/h3>\n          <p className="text-sm text-slate-600">{product.summary}<\/p>\n          <span className="text-base font-medium">${product.price}<\/span>\n        <\/div>\n      <\/div>\n    <\/article>\n  );\n}\n<\/code><\/pre>\n
Two changes. The outer wrapper is marked @container<\/code>. Every breakpoint prefix went from md:<\/code> to @md:<\/code>. That’s it. Now the card asks “am I wider than @md<\/code>?” (28rem by default, around 448px) and lays itself out accordingly. Drop it in a 320px sidebar, it stays vertical. Drop it in a 1200px hero, it goes horizontal. The page doesn’t have to tell it which one.<\/p>\n
If you’re new to Tailwind v4 in general, I wrote about my migration from v3 and what broke along the way<\/a>. Worth reading first if you haven’t moved yet.<\/p>\n
A real example: the search result that finally laid itself out right<\/h2>\n
The clearest win I had with this was on a search results page. Each result was a card with a thumbnail, title, snippet, and a row of metadata. The page itself had two layouts:<\/p>\n
    \n
  1. Full width on the results page itself.<\/li>\n
  2. A 360px “recent searches” panel in the dashboard sidebar.<\/li>\n<\/ol>\n
    With viewport-based breakpoints, the card was either right on the results page and wrong in the sidebar, or right in the sidebar and weirdly narrow on a 27-inch monitor. The fix used to be a Boolean prop compact<\/code> that flipped the layout. Maintaining two parallel sets of class names on the same component is the kind of thing you regret six months later when one of them drifts.<\/p>\n
    After the rewrite:<\/p>\n
    function SearchResult({ result }) {\n  return (\n    <article className="@container border-b py-4">\n      <div className="flex flex-col gap-3 @md:flex-row @md:gap-4">\n        <img\n          src={result.thumbnail}\n          className="aspect-video w-full rounded @md:w-32 @md:flex-shrink-0"\n          alt=""\n        \/>\n        <div className="flex flex-col gap-1 @md:flex-1">\n          <a href={result.url} className="font-medium hover:underline">\n            {result.title}\n          <\/a>\n          <p className="text-sm text-slate-600 line-clamp-2">{result.snippet}<\/p>\n          <div className="flex flex-wrap gap-x-3 gap-y-1 text-xs text-slate-500">\n            <span>{result.author}<\/span>\n            <span>{result.date}<\/span>\n            <span className="hidden @sm:inline">{result.readingTime} min read<\/span>\n          <\/div>\n        <\/div>\n      <\/div>\n    <\/article>\n  );\n}\n<\/code><\/pre>\n
    The compact<\/code> prop is gone. The hidden @sm:inline<\/code> on the reading time means the metadata row drops the least important field when there isn’t room. Notice that @sm<\/code> here means “the container is at least sm<\/code>”, not “the viewport is sm<\/code>”. For a 360px sidebar, that’s false. For a full-width results page, it’s true. Same component, two different behaviors, zero prop drilling.<\/p>\n
    The same pattern works for tables that become cards on narrow containers, for navs that collapse based on the sidebar width rather than the window width, and for media grids that re-pack themselves when the container resizes. It’s not magic. It’s just CSS finally being honest about what it should have been measuring all along.<\/p>\n
    Where I still don’t use them<\/h2>\n
    Container queries are not a free upgrade. There are places I deliberately keep using viewport breakpoints:<\/p>\n