Modern CSS: Container Queries

The Component-First Revolution

Container queries allow us to style elements based on their parent container size rather than the viewport, enabling truly modular component-based design.

For years, web developers have relied on Media Queries to create responsive layouts. While effective, Media Queries have a fundamental limitation: they only look at the width of the entire browser window (the viewport). In the modern era of component-based frameworks like React, Vue, and Web Components, this “page-down” approach often feels backwards.

Goodbye Media Queries?

Not exactly—but they are no longer the only tool in the box.

The problem with Media Queries is that a component’s style is tied to the screen size. If you have a “Card” component, it might look great in a 3-column grid on a desktop. But what if you want to reuse that same card in a narrow sidebar? With Media Queries, the card thinks it’s on a “large screen” and tries to display its wide version, which breaks the layout.

Container Queries solve this by letting the component ask: “How much space do I have in my immediate parent?”

How Container Queries Work

To use a container query, you first need to define a container context. You do this by telling the browser which element should be “watched.”

1. Define the Container

You use the container-type property. Most often, you’ll use inline-size, which tracks the width.

.card-container {
  container-type: inline-size;
  container-name: gallery-card; /* Optional: gives the container a name */
}

2. Write the Query

Instead of @media, you use @container. The styles inside this block will only apply when the .card-container meets the criteria.

/* Default styles (Stacked/Mobile-first) */
.card {
  display: flex;
  flex-direction: column;
}

/* Responsive styles based on the CONTAINER width */
@container (min-width: 400px) {
  .card {
    flex-direction: row;
    gap: 20px;
  }
}

Why This Changes Everything

1. True Reusability: You can drop a component into a sidebar, a footer, or the main content area, and it will automatically adapt its layout based on the slot it occupies.
2. Cleaner Code: You no longer need to write complex CSS selectors like .sidebar .card or .main-content .card. The card handles its own responsiveness.
3. Responsive Typography: You can even use Container Query Units (cqw, cqh, cqi, cqb, cqmin, cqmax). For example, font-size: 5cqi makes the text scale relative to the container’s width, not the screen’s.

Real-World Use Case: The Adaptive Card

Imagine a news site. On the homepage, a “Featured Story” card takes up the full width. In the “Related News” section, the same card is in a small grid cell.

With Container Queries:

• If the parent is wide, the card shows a large image next to the text.
• If the parent is narrow, the card stacks the image on top of the text.

The component is “context-aware,” making your design system significantly more robust and easier to maintain.

Current Support

As of 2024, Container Queries are supported in all major evergreen browsers (Chrome, Firefox, Safari, and Edge). While you might still need polyfills for very old enterprise environments, for most modern projects, the future has already arrived.

Final Thoughts

The shift from Viewport-Relative design to Container-Relative design is perhaps the biggest change to CSS since the introduction of Flexbox and Grid. It allows us to build components that are truly independent, modular, and smart.

Are you ready to move beyond the viewport?