CSS Container Queries

What Are CSS Container Queries?

Container queries represent a paradigm shift in CSS responsive design. Unlike traditional media queries that respond to viewport dimensions, container queries enable you to apply styles based on the size of an element's parent container. This fundamental change allows for truly modular, reusable components that adapt intelligently to their placement context rather than relying on global viewport measurements.

For years, web developers have requested this capability--components that can "know" how much space they have available and respond accordingly. Modern browser support has finally made container queries production-ready, opening new possibilities for component-based architecture and design systems. By enabling styling based on actual container dimensions rather than viewport width, container queries solve a persistent pain point in building adaptive user interfaces.

The difference is significant: with media queries alone, a card component placed in a narrow sidebar behaves the same as one in full-width main content. Container queries fix this by letting each component respond to its actual available space, creating more intuitive and maintainable responsive designs.

Setting Up Container Contexts

Before you can query a container's size, you must first establish a containment context. This tells the browser to track the container's dimensions for query purposes. The container-type property is your primary tool for creating this context.

The container-type Property

The container-type property accepts three values that determine what kind of containment is established:

• size: Creates a container that responds to both inline and block dimensions, applying full layout, style, and size containment. Use this when you need to query both width and height.

• inline-size: Creates a container that responds only to the inline dimension (width in horizontal writing modes), which is the most common use case and offers better performance since height queries aren't needed for most layouts.

• normal: Does not create a size query container but works with style queries, allowing you to query computed style values rather than dimensions.

Performance Implications

The inline-size value is generally preferred because it only requires tracking the inline dimension, reducing browser overhead. The size value applies full containment including layout and style isolation, which can improve rendering performance for complex components but has slightly higher computational cost. Choose based on your actual needs--most responsive components only require width-based queries.

Naming Containers

While optional, giving containers meaningful names enables precise targeting when multiple containers exist in your DOM. This is particularly useful in complex layouts where you want to query a specific container rather than relying on the nearest ancestor.

Container names follow a similar pattern to z-index layers--establish conventions that your team understands. Common approaches include:

• Component-based naming: card, modal, sidebar-widget
• Context-based naming: main-content, secondary-panel, featured-area
• Functional naming: adaptive-card, responsive-table, fluid-grid

When you name a container, your @container queries can target it specifically using the syntax @container name (condition). This prevents queries from accidentally matching unintended containers and gives you precise control over styling behavior.

Writing Container Queries with @container

Once you've established a containment context, use the @container at-rule to define queries that respond to container dimensions. The syntax mirrors media queries but operates at the container level rather than the viewport.

@container Syntax

The @container at-rule accepts an optional container name followed by a condition in parentheses. The condition can check for minimum or maximum dimensions, aspect ratios, or logical combinations using and, or, and not operators.

The query targets the nearest ancestor with a containment context. If that ancestor has a name, it must match the query's container name. If no name is specified in the query, any containment context will be used.

Condition Operators and Range Syntax

Container queries support both traditional conditions like min-width and modern range syntax. The new CSS media query range syntax provides a more intuitive way to express conditions:

• Traditional: (min-width: 600px) or (max-width: 400px)
• Range syntax: (width >= 600px) or (width <= 400px)
• Aspect ratio: (aspect-ratio: 16/9) or (min-aspect-ratio: 1)
• Logical combinations: @container (min-width: 500px) and (orientation: landscape)

Container Query Length Units

Container query length units provide a powerful way to create truly fluid designs that scale with the container. These units are relative to the query container's dimensions, enabling components that maintain proportions regardless of their placement. Combined with leading trim techniques for digital typesetting, you can achieve precise typography control that adapts to any container size.

Practical Applications

Container query units shine when combined with CSS math functions. The cqi unit (inline size percentage) is particularly useful for fluid typography and spacing that scales proportionally with the container. Unlike viewport units which remain constant regardless of component placement, container units adapt to each component's actual space.

When no container context exists, container query units behave like small viewport units, providing graceful degradation. For production code, always test fallback behavior to ensure components remain usable across all contexts.

Browser Support and Fallback Strategies

Container queries are now supported in all modern browsers, making them safe for production use:

• Chrome and Edge: Version 105+ (September 2022)
• Firefox: Version 110+ (November 2022)
• Safari: Version 16+ (September 2022)

Can I Use reports support above 90% globally, covering the vast majority of real-world users.

Feature Detection and Progressive Enhancement

For projects supporting older browsers, use CSS feature detection with @supports to provide appropriate fallbacks. This approach lets modern browsers enjoy container query benefits while older browsers receive traditional media query styles.

The key strategy is progressive enhancement: start with base styles that work everywhere, then enhance with container query styles for capable browsers. Use @supports not to provide fallback media query styles for legacy browsers.

When to Use Container Queries vs. Media Queries

Understanding when to use each approach is crucial for effective responsive design. These techniques are complementary rather than competing--each excels in different scenarios.

Media Queries Excel At

• Overall page layout structure changes
• Global navigation and footer behavior
• Device-specific adaptations (touch vs. pointer, dark mode)
• Document-level typography and spacing
• When components need viewport awareness

Container Queries Excel At

• Reusable component libraries and design systems
• Card-based layouts with multiple placements
• Dashboard-style interfaces with flexible grid items
• Adaptive components that work in various contexts
• Reducing CSS complexity in large applications

Decision Framework

Ask yourself: "Does this component need to adapt based on its container or the viewport?" If your component appears in multiple contexts with different available widths, container queries will simplify your CSS. If you're defining page-wide layout behavior, media queries remain the right tool. Most projects benefit from using both techniques together.

Best Practices for Container Queries

Naming Conventions

• Use semantic names based on component purpose (e.g., card, sidebar-widget)
• Avoid generic names that cause confusion in complex layouts
• Document naming conventions in your design system
• Consider scoped prefixes for large applications

Performance Optimization

• Prefer inline-size over size when you don't need height queries
• Avoid deeply nested container queries as each adds computational overhead
• Containment itself improves rendering performance by isolating elements
• Test performance on target devices early in development

Component Architecture

• Design components to be container-aware from the start
• Define breakpoints based on component needs, not arbitrary viewport widths
• Create design system tokens that work with container units
• Document container query patterns for team consistency

Integration with Design Systems

When building design systems, establish container query patterns early. Components should define their own responsive behavior through container queries rather than relying on external layout concerns. This encapsulation makes components more portable and reduces the coordination needed between components and their layouts. Understanding how many CSS properties are available helps you make informed decisions about which properties to use in your container-aware components.

Common Patterns and Use Cases

Responsive Card Components

Cards are the perfect use case for container queries. They need to adapt to different placements--sometimes in a full-width layout, sometimes in a narrow sidebar. Container queries let cards respond to their actual space rather than guessing based on viewport breakpoints. A card can display a featured layout when it has room, then gracefully collapse to a compact view when space is limited.

Adaptive Navigation Components

Navigation menus can use container queries to determine their layout based on the header width rather than the viewport. This enables the same navigation component to work in different header configurations--full-width headers, compact mobile headers, or sidebar navigation areas--each adapting appropriately.

Responsive Data Tables

Tables have traditionally been challenging to make responsive. Container queries enable tables to transform--switching from full tables with all columns visible to condensed card views--based on their actual container width. When space is limited, tables can show only key columns with expandable details, maintaining usability without horizontal scrolling.

Dashboard Widgets

Dashboard layouts often use flexible grid systems where widgets resize based on available space. Container queries let each widget define its own responsive behavior, showing more data when there's room and simplifying the display when space is constrained.

Sources

• MDN Web Docs - CSS Container Queries
• MDN Web Docs - @container At-Rule
• freeCodeCamp - Media Queries vs Container Queries
• Can I Use - Container Queries