CSS Container Queries: The Complete Guide (2026)
Container queries are the most significant CSS layout feature since Grid. While media queries respond to the viewport (browser window) size, container queries respond to a specific parent element's size. This means a card component can have different layouts based on where it is placed — sidebar, main content area, or full-width section — without any JavaScript or viewport-based hacks.
- Build truly responsive components with CSS container queries.
- Covers container queries vs media queries.
- Covers setting up container elements.
- Covers writing @container rules.
- Covers practical component patterns.
Container Queries vs Media Queries
Media queries ask: "How wide is the browser window?" Container queries ask: "How wide is my parent element?" This distinction changes everything about component design.
With media queries, a card component breaks at 768px viewport width. But what if that card is in a 300px sidebar on a 1200px screen? The viewport is wide but the card space is narrow. Media queries cannot solve this — container queries can.
Container queries make components truly reusable. Drop a component anywhere on any page, and it adapts to the space it is given. No viewport assumptions, no parent-specific overrides, no JavaScript measurement loops.
Setting Up Container Elements
To use container queries, designate a parent element as a container with two properties: container-type and container-name. container-type: inline-size enables width-based queries (the most common). container-type: size enables both width and height queries.
-webkit-backdrop-filter alongside backdrop-filter for Safari support. Without the prefix, the effect is invisible to roughly 25% of mobile users.container-name gives the container a label you reference in your @container rules. While optional, naming containers avoids ambiguity when you have nested containers.
Performance note: container-type: inline-size creates layout containment, meaning the element's internal layout cannot affect its parent size. This is what makes container queries possible — the browser can calculate the container's size before rendering its children.
Writing @container Rules
The syntax mirrors media queries: @container card-container (min-width: 400px) { ... }. Inside the block, write CSS that applies when the named container meets the condition.
backdrop-filter inside a position: fixed element can cause severe scroll performance issues. Test thoroughly on real iOS devices.You can use min-width, max-width, and logical combinations with and/or. Width is by far the most useful dimension — most responsive adjustments are about horizontal space.
Common breakpoint pattern: a card stacks vertically below 300px, goes side-by-side at 300-600px, and adds a third column above 600px. All based on the container width, not the viewport.
Practical Component Patterns
Article card: at narrow widths, stack image on top with title below. At medium widths, place image and text side by side. At wide widths, add a metadata sidebar. One component, three layouts, zero viewport assumptions.
Navigation: in a narrow sidebar, show icon-only navigation. In a wider sidebar, show icons with labels. In a full-width header, show a horizontal navigation bar. All driven by the container the nav is placed in.
Data table: at narrow container widths, switch from table layout to a stacked card layout where each row becomes a card with labeled fields. This is cleaner than horizontal scrolling.