Color scheme

Container Query Units and Style Queries

The Containers, Flex, and Sticky reading introduced container-type and @container for layout queries: changing a component's structure when its container exceeds a certain width. This topic goes further in two directions. First, container query units let you size typography, spacing, and other values relative to the container rather than the viewport, so a component can scale fluidly based on where it lives rather than how wide the screen is. Second, style queries let a component read a custom property on its container and respond to it, turning wrapper elements into a lightweight theming signal without JavaScript or class toggling.

Browser Support: Firefox and Style Queries

The interactive demo on this page uses container query units (cqi), which work in Firefox and other modern browsers. Style queries, covered in the second half of this page, currently run in Chromium-based browsers (Chrome, Edge, Arc) and Safari only. Firefox has announced plans for style queries as part of Interop 2026, but that support has not shipped as of this writing. If you are reading in Firefox and later examples seem inert, open this page in Chrome or Safari instead. When you record your Teaching Video, use a supporting browser so teammates see style queries work. Review Can I Use: CSS Container Queries (Style) for up-to-date support tables.

Container Query Units

You should already be familiar with viewport units: vw is 1% of the viewport width, vh is 1% of the viewport height. See the MDN reference if you need a refresher. Container query units work the same way, but relative to the container rather than the viewport. The full set is:

  • cqi: 1% of the container's inline size (width in horizontal writing modes)
  • cqb: 1% of the container's block size (height in horizontal writing modes)
  • cqw: 1% of the container's width regardless of writing mode
  • cqh: 1% of the container's height regardless of writing mode
  • cqmin: 1% of the smaller of cqi and cqb
  • cqmax: 1% of the larger of cqi and cqb

In practice, cqi is the one you will reach for most often. Most components respond to their available width, and cqi maps directly to that. Prefer cqi over cqw because it respects writing mode, which makes your CSS more portable across internationalized layouts.

Why Not Just Use vw?

Viewport units have a fundamental problem for reusable components: 1vw is the same value everywhere on the page, regardless of where the component is placed. A card in a 280px sidebar and the same card in a 900px main column both see the same vw. If you size the card's heading with font-size: 4vw, the sidebar card has the same oversized heading as the wide one. The layout query from the learn page fixes the structure, but the sizing values are still tied to a metric that has nothing to do with the component's actual space.

Container query units solve this. 4cqi in the sidebar card evaluates to 4% of 280px. The same 4cqi in the wide card evaluates to 4% of 900px. The font scales with the container, not the screen. This is what makes cqi-based fluid typography genuinely reusable: you define the scaling relationship once and it holds everywhere the component appears.

Fluid Typography with cqi and clamp()

Raw cqi values scale linearly with the container, which can produce text that is too small in narrow containers or too large in wide ones. Combining cqi with clamp() gives you a fluid range with hard minimum and maximum limits:


        .card-wrapper {
            container-type: inline-size;
        }

        .card-title {
            /* Minimum 1rem, preferred 4cqi, maximum 2rem */
            font-size: clamp(1rem, 4cqi, 2rem);
        }
    

This is exactly the same pattern as viewport-based fluid typography (clamp(1rem, 4vw, 2rem)), just swapping vw for cqi. The min and max remain in absolute units so the text never goes below readable size or above a comfortable heading size, and the middle value provides smooth scaling between those bounds.

You can use container query units in any CSS property that accepts a length: padding, gap, margin, width, border-radius, and so on. A card that uses cqi for its internal spacing as well as its typography will feel proportionally sized at every container width without a single media query or layout query.

The container-type: size Requirement for Block Units

There is an important constraint: cqb, cqh, and cqmax only work when the container has container-type: size, not inline-size. This is because inline-size containment only establishes a known size on the inline axis. The block axis remains intrinsically sized, so the browser cannot report a definite cqb value without creating a circular dependency.

container-type: size establishes containment on both axes, which resolves the circular dependency but comes at a cost: the container's height is no longer determined by its content. You must give it an explicit height, or it collapses to zero. This is a significant layout constraint and the reason most real-world usage sticks to inline-size containment and cqi. Only reach for size containment and block-axis units when you have an explicit height to work with, such as a fixed-height card or a viewport-spanning hero.

Setting container-type: size removes the container from normal flow height calculation. If you do not give it an explicit height, it will collapse. This is not a bug; it is the cost of two-axis containment. Use inline-size for almost everything and only reach for size when you have a controlled height context.

The demo below shows a card whose heading and body text are sized with clamp() using cqi. Drag the slider to resize the container and watch the typography scale smoothly with it, independent of the viewport width:

320px

The Sermon on the Mount

Christ's foundational teachings on discipleship, covering the Beatitudes, the higher law, and how to build a life worthy of God's kingdom.

Style Queries

Size queries ask "how wide is my container?" Style queries ask something different: "what value does a custom property on my container have?" Instead of reacting to a dimension, a component reacts to a signal its wrapper is sending through CSS. This opens up a pattern that has no clean equivalent in traditional CSS: a container can declare its intent through a custom property, and every descendant can read that signal and adapt independently.

Syntax

Style queries use the same @container at-rule as size queries, but with a style() function in the condition:


        /* The wrapper declares a theme signal */
        .promo-section {
            --variant: featured;
        }

        /* The component reads the signal from its container */
        @container style(--variant: featured) {
            .card {
                background: var(--color-status-notice-bg);
                border-color: var(--color-status-notice-fg);
            }

            .card-title {
                color: var(--color-status-notice-fg);
            }
        }
    

The .card does not need to know it is in a promo section. It just reads whatever --variant its nearest container ancestor is broadcasting and adjusts accordingly. Move the card to a different wrapper and it reads that wrapper's signal instead. The component is genuinely context-aware without any class manipulation, JavaScript, or prop drilling.

For a style query to work, the container must be established with container-type. Unlike size queries, style queries do not require inline-size or size containment specifically; any containment type qualifies. You can use container-type: inline-size for a container that responds to both size and style queries simultaneously, which is the most common real-world setup.

The Theme Token on Wrapper Pattern

The most practical use of style queries is treating a wrapper element as a theme broadcaster. You set a custom property on a section, region, or layout container, and every component inside it adapts without being individually targeted:


        /* Any wrapper can broadcast a variant signal */
        .section-dark    { --surface: dark; }
        .section-warning { --surface: warning; }
        .section-success { --surface: success; }

        /* All these wrappers are also size containers */
        .section-dark,
        .section-warning,
        .section-success {
            container-type: inline-size;
        }

        /* Components inside respond to the signal */
        @container style(--surface: dark) {
            .card { background: var(--color-surface-inverted); }
            .btn  { border-color: white; color: white; }
        }

        @container style(--surface: warning) {
            .card { background: var(--color-status-warning-bg); }
            .btn  { background: var(--color-status-warning-fg); }
        }
    

Every component inside .section-warning adapts automatically. You add a new component type to that section and it picks up the signal without any new CSS targeting that section specifically. This is what makes style queries genuinely powerful for design systems: the surface context propagates downward through the tree and every component reads it.

Compare this to the class-toggling approach, where you would write .section-warning .card, .section-warning .btn, .section-warning .badge, and so on. Every new component requires a new selector for every surface variant. Style queries collapse that matrix into one query per component.

What Style Queries Cannot Do

Style queries read custom properties, not computed values. You cannot write @container style(background-color: red) to detect a red background. The query only works with custom properties you explicitly set. This is intentional: computed value detection would create circular dependencies and unpredictable cascade behavior. Think of style queries as explicit signals you design into your system, not a way to inspect arbitrary CSS state.

Style queries also cannot query inherited values that were not set directly on the container. If --variant is inherited from a grandparent but not explicitly declared on the immediate container, the query will not fire on that container. The property must be set at the containment boundary.

Teaching Video Checklist

When you record your teaching video, make sure your teammates come away understanding these concepts:

  • What cqi measures and why it produces more reusable fluid typography than viewport-based vw units, demonstrated by placing the same component in two different-width containers and showing how cqi scales differently in each while vw would not
  • How clamp() and cqi combine to create fluid typography with hard limits, and what happens at the minimum and maximum bounds
  • Why cqb and block-axis units require container-type: size and what that costs, so teammates know when to avoid it
  • The style query @container style() syntax, what a style container is, and the theme token on wrapper pattern demonstrated with a live component reacting to a custom property signal
  • An honest and specific statement of current browser support for style queries: which browsers work today, which do not, and what your fallback approach would be in a production project

Start by resizing a container in DevTools with and without cqi units so your teammates can see the difference live. Then show the style query pattern by toggling a custom property value in DevTools on a wrapper element and watching the component inside react without any class changes.

Resources