CSS Container Style Queries: Let the Parent Set the Theme

Design systems often struggle with a "modifier class problem," where components like cards need different styles for various contexts, such as dark themes or compact layouts. This leads to unnecessary complexity due to the need for multiple class names and selectors.

Container style queries, a feature introduced in 2023, allow parent elements to set custom properties that influence their descendant elements' styles. This solves the context-based styling issue by enabling components to react to the themes or variants they are placed in, rather than just their viewport size.

Style queries work by using a @container rule with a style function that checks the computed value of a custom property on an ancestor element. If the value matches the specified condition, the nested rules apply to the descendants. This approach requires only custom properties, which are supported by most modern browsers.

However, a common mistake is attempting to query a custom property set on the same element. Instead, the property should be set on a child or wrapper element. This is a crucial point to remember to avoid unexpected behavior.

The syntax for range queries, which allow comparing values instead of matching exact strings, was added in 2023. This feature enables more nuanced styling based on numeric values, such as the fill level of a meter component.

A recommended approach is to style components with default values outside any style queries and then layer the contextual variants inside the @container style() blocks. This additive approach ensures that browsers without support for style queries will still render the default styles, without any layout or functionality issues. Over time, as browser support improves and analytics show reduced usage of fallbacks, the need for modifier classes can be phased out.