CSS Container Queries: Style Components, Not Just Pages

Why it exists

Traditional media queries only know about the browser viewport. This makes it hard to build components that can be dropped into any layout, as their styling is tied to the page size, not their own allocated space. Container queries solve this by letting components query their parent's dimensions and adapt accordingly.

The mental model

Think of container queries as media queries for elements. Instead of asking "how wide is the browser window?", a component asks "how wide is the box I've been placed in?". This decouples the component's styling from the page's layout, making it truly portable and self-contained.

How it works

Using container queries is a two-step process. First, you must establish a "containment context" on a parent element. You do this with the container-type property, for example, container-type: inline-size;. This tells the browser to start tracking that element's size. Second, you write an @container rule targeting a child element. This rule contains a condition, like (min-width: 400px), and applies specific styles only when the container meets that condition. You can also name containers with container-name for more complex layouts.

When to use it

Use container queries for any component that needs to adapt its layout based on the space it's given. This is ideal for card-based UIs, dashboard widgets, sidebars, and any component in a design system intended for reuse across different contexts. They allow a single component to look right in a main content area or a narrow aside without modification.

When not to use it

For global, page-level layout changes, like switching a whole website from a three-column desktop view to a single-column mobile view, traditional media queries are still the right tool. Container queries are for component-level adaptation, not rearranging the entire page structure.

One canonical example

Imagine a product card. In a wide column, the image is beside the text. In a narrow column, the image should stack on top. First, define the container: .grid-cell { container-type: inline-size; }. Then, write the query for the card inside it: @container (max-width: 350px) { .product-card { flex-direction: column; } }. Now the card's layout is determined by the grid cell's width, not the whole page.