tutorial

CSS Container Queries — When Components Become Self-Aware

Mar 30, 2026

For some people, creating responsive layouts might just mean throwing a bunch of media queries into the CSS or using 15 tailwind classes on a component.

You add some media queries, tweak a few breakpoints, maybe fight with a flexbox layout for a bit, and eventually things look… acceptable.

But there was always this subtle problem:

My components didn’t actually know where they were.

They only knew how big the screen was.

And that worked for us, for a while. As we started building more complex layouts with deeply nested UI components, we needed a better way to have those parts of our layout adjust to the space available. Sure we could use javascript, but that was a workaround, a hack if you will.

The Problem with Thinking in Viewports

Most of us learned responsive design like this:

@media (min-width: 768px) {
  .card {
    flex-direction: row;
  }
}

Seems reasonable, right?

But here’s the catch:

  • What if that card is in a narrow sidebar on a large screen?
  • What if it’s in a wide grid on a small screen?
  • What if your layout changes, but your breakpoints don’t?

Suddenly your “responsive” component isn’t very responsive.

It’s reacting to the viewport, not the space it actually has.

What we really needed:

  • “If this card has enough space, lay things out horizontally”
  • “If it doesn’t, stack them vertically”

Not:

  • “If the browser window is wide enough, hope for the best”

Container Queries to the rescue

Instead of asking:

“How big is the screen?”

You ask:

“How much space do I have?”

Here’s the key idea:

  • Media queries → global (viewport-based)
  • Container queries → local (component-based)

The Only Thing You Need to Remember

Before anything works, you need to tell CSS:

“Hey, this element is a container now.”

.dashboard-section {
  container-type: inline-size;
}

That’s it. That’s the switch.

(And yes, you will forget to add this at least once and question your life choices.)

A Real Example: A Card in a Dashboard

Let’s say you have a dashboard with reusable cards.

Each card has:

  • an image or icon
  • some text
  • maybe an action button

Default (Tight Space)

When the card is in a narrow column, you want this:

  • stacked layout
  • easy to scan
  • vertical flow
.card {
  display: flex;
  flex-direction: column;
  gap: 1rem;
}

When There’s More Space

If the card is placed in a wider section of the dashboard, you want:

  • image on the left
  • content on the right
  • more efficient use of space

With container queries:

@container (min-width: 400px) {
  .card {
    flex-direction: row;
    align-items: center;
  }
}

Why This Is Actually a Big Deal

Now your card behaves based on where it lives, not where the page is.

So the same component can:

  • sit in a sidebar → stack vertically
  • sit in a main panel → switch to horizontal
  • live in a grid → adapt naturally

No extra classes. No layout-specific overrides. No guessing breakpoints.

Just:

“Do I have enough space? Yes? Cool, I’ll adjust.”

The Subtle Shift in Thinking

This is the part that took me a bit to internalize:

You stop designing pages… and start designing components that adapt themselves.

Your components become:

  • more reusable
  • more predictable
  • less dependent on context

They stop being fragile.

A Few Gotchas (Because Of Course There Are)

A couple things that tripped me up:

  • You must set container-type on a parent element
  • Not everything should be a container — be intentional
  • It’s easy to overuse this when a simple media query would do

And yes:

If nothing is working, check container-type first.

Always.

When to Use Container Queries

They shine when:

  • you’re building reusable components
  • your layout changes depending on placement
  • you’re working in design systems or dashboards

They’re less necessary when:

  • you’re doing full-page layout shifts
  • your design is tightly tied to viewport sizes

Media queries aren’t going anywhere — this just gives you a better tool for the right job.

Final Thoughts

Container queries didn’t just give us a new feature.

They fixed a mismatch that’s been there for years.

We were building components… but styling them like pages.

Now those two things finally line up.

And once you start thinking this way, going back to viewport-only logic feels a little… off.

If you haven’t used container queries yet, try them on something small — like a card.

That’s usually all it takes for things to click.