Chapter 10: Container queries
This introduction explains why viewport-based media queries can fall short for reusable modules and introduces the two kinds of container queries.
After this chapter you will be able to
- Limits of viewport queries. Explain why a media query based on viewport size may not make a reusable module responsive to the space it actually has.
- Container query types. Distinguish container size queries from container style queries and describe what a container means in this context.
- Viewport breakpoint mismatch. Explain how the page and media module respond at small and large viewport sizes, and why the module becomes cramped at an intermediate size.
- Container size and modularity. Justify using container queries rather than adding viewport media queries for this module.
- Container definition and size query. Explain how to define a container with container-type and use @container to apply styles when that container meets a width condition. Describe how an optional container-name identifies the queried container and how the container shorthand can set both properties.
- Module response to available width. Describe how the media module changes layout as its available container width changes, and explain why this keeps the sidebar’s code separate from the module’s code.
- Containment and query feedback. Explain why a container query cannot change the queried container’s size and why that size must not depend on its children.
- Normal and inline-size containers. Distinguish the default normal container type from inline-size, including which size queries inline-size supports and how its dimensions are determined.
- Full-size container requirements. Explain when size enables height queries and what must establish a size container’s height.
- Named container selection. Explain how a named container query selects an ancestor, why nonmatching containers are skipped, and how multiple names on one container can be used.
- Unnamed container query behavior. Distinguish how an unnamed query finds its container from how a named query does, and state how to define a container without a name.
- Predictable Containers for Modules. Explain why a module element that may hold other modules should be made a container. Describe how the media module applies this strategy to media__body and why layout elements must also define containers.
- Container-relative unit meanings. Describe what the six container-relative units measure and how they differ from viewport-relative units.
- Responsive card sizing. Explain how cqi sizes the example cards’ headings and images, and why this use does not need an @container query.
- Conditional styles from custom properties. Explain how a container style query uses style() to apply CSS to descendants when an element inherits a specified custom property value.
- Sidebar-driven card layout. Explain how setting the --sidebar custom property lets a style query change the race-detail card’s layout in the sidebar.
- Style-query decoupling tradeoffs. Distinguish the style-query approach from a DOM-location selector and an HTML module variant, including when a variant may be preferable.
- Shared theme style query. Explain how a custom property and style query let different triggers apply the same styles without repeating rules.
- Dark-mode selection flow. Trace how the example selects a theme on page load, lets the user change it, and applies dark-mode adjustments to modules.
What it builds on
- Media queries (chapter 7) · Media queries for responsive design.
- Defining modules (chapter 9) · Organizing CSS into reusable modules.
- Adding breakpoints to the page (chapter 7) · Using viewport breakpoints to change responsive layouts.
- Variations of a module (chapter 9) · Introduces variations of a CSS module.
- Viewport-relative units (chapter 2) · The comparison with viewport-relative units.
- Custom properties (aka CSS variables) (chapter 2) · Introduces CSS custom properties.
- Progressive enhancement (chapter 1) · Introduces progressive enhancement.
Section by section
Introduction
This introduction explains why viewport-based media queries can fall short for reusable modules and introduces the two kinds of container queries.
- Limits of viewport queries: Explain why a media query based on viewport size may not make a reusable module responsive to the space it actually has.
Why it matters: It explains why a reusable module may need to respond to its surroundings rather than the whole page. - Container query types: Distinguish container size queries from container style queries and describe what a container means in this context.
Why it matters: The distinction identifies which aspect of a module's surroundings each kind of query responds to.
Key terms: module, viewport, @media query, container, container size queries, container style queries, custom property
10.1 A basic example of a container query
A media module in a narrow sidebar shows why viewport-based media queries can fail for reusable components and why container size is a better basis for their responsive layout.
- Viewport breakpoint mismatch: Explain how the page and media module respond at small and large viewport sizes, and why the module becomes cramped at an intermediate size.
Why it matters: A page-wide breakpoint may not reflect the space a component actually has. - Container size and modularity: Justify using container queries rather than adding viewport media queries for this module.
Why it matters: Responding to available container space makes a module easier to reuse in different parts of a page.
Key terms: media module, media queries, viewport, sidebar, container queries, modular design, container
10.1.1 Using container size queries
This subsection shows how to define a container and use its width to adapt a media module’s descendants without tying the module’s styles to the sidebar’s styles.
- Container definition and size query: Explain how to define a container with container-type and use @container to apply styles when that container meets a width condition. Describe how an optional container-name identifies the queried container and how the container shorthand can set both properties.
Why it matters: It lets a component respond to the space its container provides rather than relying only on the viewport width. - Module response to available width: Describe how the media module changes layout as its available container width changes, and explain why this keeps the sidebar’s code separate from the module’s code.
Why it matters: The module can choose an appropriate layout wherever it is placed, even when the sidebar changes the space available to it. - Descendant-only query styling: State which elements a container query can style and why it cannot style the container itself.
Why it matters: This boundary determines where the styles controlled by a container query can be applied. - Negated container conditions: Describe how not reverses a container query condition, using the width example from the section.
Why it matters: It provides a way to target the opposite of a stated container-size condition.
Key terms: container-type, container-name, container, @container, media module, sidebar, breakpoints, container query, descendant elements, not
10.2 A closer look at containers
This section introduces a closer examination of container names, types, and restrictions without yet explaining how they work.
10.2.1 Container types
Explains how containment prevents container-query feedback loops and how each container type affects which dimensions can be queried.
- Containment and query feedback: Explain why a container query cannot change the queried container’s size and why that size must not depend on its children.
Why it matters: This explains why container types impose sizing restrictions rather than simply allowing queries against any element. - Normal and inline-size containers: Distinguish the default normal container type from inline-size, including which size queries inline-size supports and how its dimensions are determined.
Why it matters: Choosing inline-size allows the common width-based responsive behavior without requiring an independently established height. - Full-size container requirements: Explain when size enables height queries and what must establish a size container’s height.
Why it matters: Height queries only work as intended when the container has a height established independently of its children.
Key terms: containment, container query, container-type, normal, inline-size, inline size, flex-basis, flex-grow, size, full-size containment
10.2.2 Container names
This section explains how container names determine which ancestor a container query uses, including what happens when names are omitted.
- Named container selection: Explain how a named container query selects an ancestor, why nonmatching containers are skipped, and how multiple names on one container can be used.
Why it matters: Names let a query target the relevant ancestor rather than simply the closest container. - Unnamed container query behavior: Distinguish how an unnamed query finds its container from how a named query does, and state how to define a container without a name.
Why it matters: Leaving a name out changes which ancestor a query may use.
Key terms: container name, matching name, container ancestor, DOM, container-type, container shorthand property, container query
10.2.3 Containers and modular CSS
This section shows how consistently defined containers let nested CSS modules respond to their available space without requiring a wrapper around every module.
- Predictable Containers for Modules: Explain why a module element that may hold other modules should be made a container. Describe how the media module applies this strategy to media__body and why layout elements must also define containers.
Why it matters: A nested module can respond reliably only when the page provides containers in predictable places. - Media Body Width: Describe the additional media__body change made alongside defining it as a container and its stated purpose.
Why it matters: The example addresses the width of the element being used as a container, not just its container designation. - Module Query Strategy: Explain why the author generally favors container queries over media queries for modules, and describe the tradeoff of giving a module its own wrapper container.
Why it matters: This tradeoff helps you choose a consistent module strategy without adding a wrapper to every instance.
Key terms: modular CSS, container, media__body, layout styles, flex-grow, container queries, media queries, media-container, container-type: inline
10.3 Container-relative units
This section defines container-relative units and shows how they make card dimensions respond to their containers without requiring an @container query.
- Container-relative unit meanings: Describe what the six container-relative units measure and how they differ from viewport-relative units.
Why it matters: These meanings let you predict what a container-relative length will respond to. - Block-direction unit fallback: Explain what happens when a block-direction unit is used with an inline-size container.
Why it matters: The fallback explains why a block-direction value may not track the nearest inline-size container. - Responsive card sizing: Explain how cqi sizes the example cards’ headings and images, and why this use does not need an @container query.
Why it matters: Container-relative units can provide continuous responsiveness even when no conditional container rule is needed.
Key terms: container-relative units, query container, cqw, cqh, cqi, cqb, inline-size container, size type container, block-direction units, clamp()
10.4 Container style queries
This section introduces container style queries as a way to conditionally style descendants based on an inherited custom property, and notes their limited browser support.
- Conditional styles from custom properties: Explain how a container style query uses style() to apply CSS to descendants when an element inherits a specified custom property value.
Why it matters: It lets a component’s descendants respond to a style value rather than only to available space. - Style queries versus size queries: Distinguish style queries from size queries and explain why style queries do not require an explicitly defined container.
Why it matters: This distinction prevents you from assuming that a style query needs the same container setup as a size query. - Style query browser support: Describe the section’s browser-support warning and the resulting recommendation for using style queries.
Why it matters: The support warning helps you decide whether to rely on style queries in a design.
Key terms: container style queries, style(), custom property, descendant elements, container size queries, size containment, progressive enhancement, experimental, browser support
10.4.1 Decoupling a module from its container
Shows how a container style query lets a race-detail card adapt to a sidebar without tying the card’s styles to that particular page layout.
- Sidebar-driven card layout: Explain how setting the --sidebar custom property lets a style query change the race-detail card’s layout in the sidebar.
Why it matters: The same card can take on a sidebar-appropriate layout when its context calls for it. - Style-query decoupling tradeoffs: Distinguish the style-query approach from a DOM-location selector and an HTML module variant, including when a variant may be preferable.
Why it matters: Choosing who controls a module’s variation helps keep its styles reusable without ruling out useful HTML variants.
Key terms: style query, --sidebar, race-detail, inline size, modular CSS, module variant, selector specificity
10.4.2 Reducing code duplication
This subsection uses a dark-mode example to show how container style queries can share CSS across multiple theme triggers without duplicating rules, while noting browser-support limits.
- Shared theme style query: Explain how a custom property and style query let different triggers apply the same styles without repeating rules.
Why it matters: The shared query keeps theme-related CSS from becoming repetitive as more modules need adjustments. - Dark-mode selection flow: Trace how the example selects a theme on page load, lets the user change it, and applies dark-mode adjustments to modules.
Why it matters: This connects the shared-query idea to both an initial operating-system preference and an explicit user choice. - Style-query fallback planning: Explain why the section recommends caution with container style queries and how to plan fallback styles.
Why it matters: A usable fallback matters when a browser cannot apply the queried styles.
Key terms: style query, custom property, code duplication, prefers-color-scheme, --color-theme, data-theme, light mode, dark mode, container style queries, progressive enhancement
10.5 Summary
Concepts explained in this chapter
- container style queryThe CSS style() function expresses a container-query condition based on the computed value of a custom property on the query container.
- @containerA CSS container size query is a conditional query that evaluates the size of an explicitly defined ancestor query container.
- container typeThe CSS container-type property establishes an element as a query container and specifies the dimensions or characteristics it exposes to container queries.
- containerA container element in container queries is a specific ancestor element whose size or styles provide the reference for querying a descendant.
- moduleA module is a reusable, relatively small unit of page structure and styling that is independent of its surrounding page context.
- modular cssModular CSS is an approach to organizing styles into reusable, relatively independent modules rather than applying one undifferentiated set of global rules.
These guides are generated from the text of Manning books by Manning's knowledge graph and link to the sections they draw on. The full books are available on liveBook and at manning.com.