CSS Container Queries

Definition

CSS Container Queries let an element's styles respond to the size (or other characteristics) of its containing element, rather than only the overall browser viewport, as with traditional media queries. This enables components to be truly responsive based on the space they're actually given, regardless of where they're placed on the page.

Overview

Traditional responsive design with `@media` queries styles elements based on properties of the viewport — typically its width — which works well for page-level layout but breaks down for reusable components that might appear in many different contexts on the same page: a card component in a wide main content area needs different styling than the same card component squeezed into a narrow sidebar, even though the viewport width hasn't changed. Historically, this forced developers into either writing bespoke variant classes per context or using imprecise proxies for available space. Container Queries solve this directly: a developer marks an ancestor element as a 'containment context' using the `container-type` CSS property (typically `inline-size`, to query based on width), optionally naming it with `container-name`, and then descendant elements can use `@container` rules to apply styles conditionally based on that container's actual rendered size — not the viewport's. This means the exact same component markup and CSS can automatically adapt its layout, font sizes, or visibility of secondary content based purely on how much space its parent container currently has, whether that's a full-width hero section or a cramped sidebar widget. Container Queries were a long-requested CSS feature, discussed for years before browser vendors converged on the `container-type`/`@container` syntax, and reached broad cross-browser support in 2023. They pair naturally with component-based frontend architectures (React, Vue, Web Components), where the same component is authored once but rendered in many different layout contexts, making 'context-aware responsiveness' a property of the component itself rather than something the page author has to hand-manage. A closely related but distinct feature, container style queries, extends the same containment concept to querying custom property values on a container rather than just its size, though support for style queries has lagged behind size-based container queries.

Key Concepts

• Styles elements based on their containing element's size, not the viewport
• Enabled via `container-type` on an ancestor and `@container` rules on descendants
• Supports named containers via `container-name` for targeting specific ancestors
• Makes truly reusable, context-aware components possible without JavaScript
• Reached broad cross-browser support in 2023
• Complements (doesn't replace) traditional viewport-based `@media` queries
• Container style queries extend the concept to custom property values, not just size
• Works natively with component-based frameworks like React and Web Components

Use Cases

Frequently Asked Questions

Related in Web