CSS Container Query Proposal & Explainer

Table of Contents
Archived:

✅ This feature has shipped in browsers. Our notes are likely out-of-date.

Authors

Miriam Suzanne

Participate

The CSSWG has resolved to begin moving this proposal into the CSS specification, as part of the CSS Containment Module level 3. (So far, that’s an empty document. I’m working on it.)

Please leave any feedback on the CSSWG issues for this proposal:

Implementations:

This Document:

See the resources page for links to articles and demos.

Table of contents

Introduction

Media-queries allow an author to make style changes based on the overall viewport dimensions – but in many cases, authors would prefer styling modular components based on their context and available space within a layout. Earlier this year, David Baron & Brian Kardell proposed two complementary approaches to explore: a @container rule, and a switch() function. Both could be useful in different cases.

This proposal builds on David Baron’s @container approach, which works by applying size & layout containment to the queried elements. Any element with both size & layout containment can be queried using a new @container rule, with similar syntax to existing media-queries. Currently, size containment is all-or-nothing. In order to make that less restrictive for authors, I’m also proposing inline-size & block-size values for the contain property.

This is an early outline of the feature as I imagine it in the abstract – but there are a number of questions that could only be resolved with a prototype. The purpose of this document is to outline a direction for more testing & exploration.

Goals

Often the layout of a page involves different “container” areas – such as sidebars and main content areas – and then component parts that can be placed in any area. Those components can be complex (a full calendar widget) or fairly simple (heading typography), but should respond in some way to the size of the container.

This can happen at multiple levels of layout – even inside nested components. The important distinction is that the “container” is distinct from the “component” being styled. Authors can query one to style the other.

Non-goals

Modern layouts provide a related problem with slightly different constraints. When using grid layout, for example, available grid-track size can change in ways that are difficult to describe based on viewport sizes – such as shrinking & growing in regular intervals as new columns are added or removed from a repeating auto-fit/auto-fill grid.

In this case there is no external “container” element to query for an accurate sense of available space.

There is a reasonable workaround, but an ideal solution might look more like Brian Kardell’s switch() proposal – which allows a limited set of properties to query the space available, rather than any explicit container. It would be good to consider these approaches in tandem.

Improvements to flexbox & grid – such as indefinite grid spans or first / last keywords – could also improve on the existing flexibility of those tools.

And finally, authors often want to smoothly interpolate values as the context changes, rather than toggling them at breakpoints. That would require a way to describe context-based animations, with breakpoint-like keyframes.

Proposed Solutions

Single-axis containment (inline-size & related values)

This is a proposed change to the CSS Containment Module, specifically size containment.

In order for container-queries to work in a performant way, authors will need to define container elements with explicit containment on their layout and queried-dimensions. This can be done with the existing contain property, using the size and layout values:

.container {
  contain: size layout;
}

While that will work for some use-cases, the majority of web layout is managed through constraints on a single (often inline) axis. Intrinsic sizing on the cross (often block) axis is required to allow for changes in content, font size, etc.

I’m proposing new single-axis values for contain, starting with inline-size:

.inline-container {
  contain: inline-size;
}

This is both the most common use-case, and the most likely to be implementable. If we find that it’s also possible to support 1D containment on the block axis, we should also support the block-size logical value, and width/height physical values:

.block-container {
  contain: block-size;
}

.width-container {
  contain: width;
}

.height-container {
  contain: height;
}

Elements with single-axis containment should have their intrinsic and final layout on the specified axis determined without any contributions from their children. In most cases, that should be the same as current contain: size behavior, only applied to the axis in question.

Of these values, it is clear that block-size has the fewest use-cases, and more potential implementation issues. While I’m not ready to eliminate it immediately, support for block-size would not be required to make container queries useful. Since both width and height values may refer to the block size in a given instance, they pose the same potential issues.

See the discussion of single-axis containment issues for more detail.

Containment context

Ideally, container queries could be resolved against the available space for any given element. Since size and layout containment are required, we instead need to define the containment context for each element.

I propose that any element with appropriate containment on a given axis generates a new containment context in that axis, which descendants can query against:

.two-axis-container {
  /* establishes a new containment context on both axis */
  contain: layout size style;
}

.inline-container {
  /* establishes a new containment context on the inline axis */
  contain: layout inline-size style;
}

.block-container {
  /* establishes a new containment context on the block axis */
  contain: layout block-size style;
}

When size-containment is only available on a single axis, queries on the cross-axis will not resolve against that query context.

When no containment context is established, container queries are not applied.

Container queries (@container)

This could be added to a future level of the CSS Conditional Rules Module. Unless otherwise noted, @container should follow the established specifications for conditional group rules.

The @container rule can be used to style elements based on their immediate containment context, and uses a similar syntax to existing media queries:

/* @container <container-query-list> { <stylesheet> } */
@container (inline-size > 45em) {
  .media-object {
    grid-template: "img content" auto / auto 1fr;
  }
}

This would target any .media-object whose containment context (nearest ancestor with containment applied) is greater-than 45em.

Unlike media-queries, each element that is targeted by a conditional group rule will need to resolve the query against its own containment context. Multiple elements targeted by the same selector within the same group may still resolve differently based on context. Consider the following CSS & HTML together:

/* css */
section {
  contain: layout inline-size;
}

div {
  background: red;
}

@container (inline-size > 500px) {
  div {
    background: yellow;
  }
}

@container (inline-size > 1000px) {
  div {
    background: green;
  }
}
<!-- html -->
<section style="width: 1500px">
  <!-- container 1 -->
  <div>green background</div>

  <section style="width: 50%">
    <!-- container 2 (nested) -->
    <div>yellow background (resolves against container 2)</div>
  </section>
</section>
<section style="width: 400px">
  <!-- container 3 -->
  <div>red background</div>
</section>

Container features

Like media-queries, @container needs a well defined list of “features” that can be queried. The most essential container features are the contained dimensions:

When containment is available on both axis, we might also be able to query dimensional relationships such as:

Since container queries resolve against styled elements in the DOM, it may also be possible to query other aspects of the container’s computed style?

This needs more discussion and fleshing-out.

Container query list

Like media-queries, container-queries can be combined in a list, using the same syntax and following the same logic as media-query-lists:

A media query list is true if any of its component media queries are true, and false only if all of its component media queries are false."

–Media Queries 4

Key scenarios

Modular components in any container

Page layouts often provide different layout “areas” that can act as containers for their descendant elements. These can be nested in more complex ways, but let’s start with a sidebar and main content:

<body>
  <main>...</main>
  <aside>...</aside>
</body>

We can establish a responsive layout, and declare each of these areas as a containment context for responsive components:

body {
  display: grid;
  grid-template: "main" auto "aside" auto / 100%;
}

@media (inline-size > 40em) {
  body {
    grid-template: "aside main" auto / 1fr 3fr;
  }
}

main,
aside {
  contain: layout inline-size;
}

Now components can move cleanly between the two areas – responding to container dimensions without concern for the overall layout. For example, some responsive defaults on typographic elements:

h2 {
  font-size: 120%;
}

@container (inline-size > 40em) {
  h2 {
    font-size: calc(130% + 0.5vw);
  }
}

Or “media objects” that respond to available space:

.media-object {
  grid-template: "img" auto "content" auto / 100%;
}

@container (inline-size > 45em) {
  .media-object {
    grid-template: "img content" auto / auto 1fr;
  }
}

Components with internal containers

A more complex component, like a calendar, might reference external context while also defining nested containers:

<section class="calendar">
  <div class="day">
    <article class="event">...</article>
    <article class="event">...</article>
  </div>
  <div class="day">...</div>
  <div class="day">...</div>
</section>
.day {
  contain: layout inline-size;
}

/* despite having different containers, these could share a query */
@container (inline-size > 40em) {
  /* queried against external page context */
  .calendar {
    grid-template: repeat(7, 1fr);
  }

  .day {
    border: thin solid silver;
    padding: 1em;
  }

  /* queried against the day */
  .event {
    grid-template: "img content" auto / auto 1fr;
  }
}

Component in a responsive grid track

In some situations, there is no clear “container” element defining the available space. Consider the following HTML & CSS:

<section class="card-grid">
  <div class="card">...</div>
  <div class="card">...</div>
  <div class="card">...</div>
  <div class="card">...</div>
</section>
.card-grid {
  display: grid;
  grid-template-columns: repeat(auto-fit, minmax(20em, 1fr));
}

.card {
  display: grid;
  /* we want to change this value based on the track size */
  grid-template: "image" auto "content" 1fr "footer" auto / 100%;
}

The size of .card-grid does not accurately reflect the available space for a given card, but there is no other external “container” that .card can use to adjust the grid-template.

Authors using this proposal would need to add an extra wrapping element – so that the card component has an external track-sized container to query:

<section class="card-grid">
  <div class="card-container"><div class="card">...</div></div>
  <div class="card-container"><div class="card">...</div></div>
  <div class="card-container"><div class="card">...</div></div>
  <div class="card-container"><div class="card">...</div></div>
</section>
/* the outer element can get containment… */
.card-container {
  contain: layout inline-size;
}

/* which gives .card something to query against */
@container (inline-size > 30em) {
  .card {
    grid-template: "image content" 1fr "image footer" auto / 1fr 3fr;
  }
}

There are already many similar situations in CSS layout – so this might be a viable solution for most use-cases – but the extra markup is not ideal.

Combining media & container queries

In many cases, container queries would replace existing media-queries – making the same underlying goals more clear and reliable.

Often media-queries will remain in place for managing page-wide concerns, like responsive font sizing or outer page layouts. Often I expect the layout areas generated by media-queries to become containers for their descendant components. As discussed above:

body {
  display: grid;
  grid-template: "main" auto "aside" auto / 100%;
}

@media (inline-size > 40em) {
  body {
    grid-template: "aside main" auto / 1fr 3fr;
  }
}

main,
aside {
  contain: layout inline-size;
}

But there are also situations where an author might want to query container width, along with viewport height. This allows a design to respond to both dimensions, without requiring containment on both axis, or a defined container height:

@media (height > 35em) {
  @container (width > 40em) {
    .card {
      grid-template: "img    header" auto
                     "img    main" 1fr
                     "footer footer" auto
                    / minmax(15em, 1fr) 3fr;
    }
  }
}

Beyond basic dimensions, it’s likely that container queries will also be combined with queries of media type, interface, or preferences. For example, a container query that is specific to print media:

@media print {
  @container (width > 20em) {
    .card { /* ... */ }
  }
}

Migration path

See the CSSWG issue for more details.

While at-rules provide their own test for positive support, there is currently no way to test for lack of at-rule support.

@container (<query>) {
  /* progressive enhancements */
}

/* query negative support for the related new property/value */
@supports not <what-goes-here?> {
  @media (...) { /* fallback media-queries */ }
}

In order to provide a reliable migration path, we need two things:

For the new syntax, we’re proposing:

@supports container(<query>) {
  /* <guery> is supported on containers */
}

@supports not container(<query>) {
  /* <guery> is not supported on containers */
  /* (testing support of the specific query) */
  /* OR @supports container() syntax is not supported */
  /* (testing support of container-queries broadly) */
}

For example:

/* test for general CQ support */
@supports container(min-width: 1em) { ... }

/* test for range syntax */
@supports container(width > 1em) { ... }

Currently, browsers handle unknown @supports syntax inconsistently. For the positive test, they all resolve to false (not supported), but for the negation of that same test, they disagree:

Code Firefox Chromium WebKit
not foo() true false false
not foo(bar) true true false
not (foo()) true false true
not (foo(bar)) true true true

The ideal result here is true (not false). While we wait for browsers to fix this inconsistency, though, Authors can wrap the container() syntax in parenthesis:

@supports not (container(<query>)) { ... }

Detailed design discussion & alternatives

Single-axis containment issues

CSSWG issue:

There are two known situations in CSS where changes on the block-axis can have an impact on the inline-axis layout:

  1. When an ancestor of the contained element has auto scrolling, extra cross-axis size can cause scrollbars to appear on the contained-axis. This is only an issue when all three are true:

    • Scrollbars are part of the layout flow (they are not overlaid)
    • Overflow on the cross-axis is set to auto on any ancestor
    • The contained size is impacted by the size of that ancestor

  2. Block-axis percentage padding & margins are resolved relative to the inline available size. That would cause issues when:

    • Containment is on the block-axis
    • Any ancestor has inline-size determined by contents (float+auto, min-content, max-content, etc)
    • Any intermediate ancestor has:
      • box-sizing of border-box
      • height determined by the outer ancestor
      • % padding on the block-axis (so inner-height decreases as outer-width increases)
    • The container block-size is impacted by the inner-size of that ancestor

    See contain-y comment) and related codepen demo.

    That issue is most likely to occur when containing the block-axis, but nested writing modes can flip the impacted axis (contain-x with writing modes).

There are likely more issues that would be revealed during implementation – but I expect the number to remain low.

These are not entirely new issues. The sizing/layout specs all have module-specific caveats for handling percentages based on available size. The proposal is to begin prototyping this feature, and attempt to address each issue as they arise – using similar workarounds. For example:

Those are not final solutions, but examples for how we might be able to solve each case as it arises.

Implicit vs explicit containers

CSSWG issue:

In conversations leading to this proposal, there has been some concern about the dangers of establishing context implicitly based on the value of contain. Similar behavior for positioning & stacking has sometimes been confusing for authors.

David Baron’s proposal included a selector for querying a container more explicitly:

/* syntax */
@container <selector> (<container-media-query>)? {
  /* ... */
}

/* example */
@container .media-object (inline-size > 45em) {
  .media-object {
    grid-template: "img content" auto / auto 1fr;
  }
}

Since all known use-cases attempt to query the most immediate available space, I don’t see any need for querying containers with an explicit syntax, or any way to “skipping over” one container to query the next.

Adding a selector to the query would also raise new problems:

However, it might be helpful to consider a more explicit way of defining the containers initially, to make this more clear for authors – such as query, inline-query, & block-query values that would apply both layout and size containment. This needs more discussion & consideration.

Combining scope with container queries

David Baron’s proposal also uses the explicit container selector to attach the concept of scope to containers – only matching selectors inside the query against a subtree of the DOM.

This might be useful for use-cases where a component both:

But in my exploration of use-cases, it seems more common that components will want to query external context, while establishing internal scope.

There is also a mis-match where authors expect to style the root element of a given scope, but should not be able to style the root of a container-query.

For those reasons, I think the two features – container queries and scope – should remain distinct, and be solved separately.

@-Rule or pseudo-class?

Many proposals & Javascript implementations use a pseudo-class rather than an @-rule.

/* pseudo-class */
.selector:container(<query >) {
  /* ... */
}

I think the @-rule block provides several advantages:

The issue of making multiple changes in a single query could also be resolved with a selector syntax once CSS Nesting has been implemented. These would likely have the same meaning:

@container (inline-size < 40em) {
  & .card { /* ... */ }
}

.card:container(inline-size < 40em) {
  /* ... */
}

There’s even a potential advantage here for the selector syntax, as it allows authors to query a container at a different point in the selector (not just the targeted element).

.card:container(inline-size < 40em) {
  & h2 { /* nesting syntax... */ }
}

That’s not easily represented by any @container syntax.

Stakeholder Feedback / Opposition

References & acknowledgements

This proposal is based on the previous work of many people:

Thanks also for valuable feedback and advice from:

Changelog

2021.05.12

2021.05.11

2021.04.02

2021.03.26

2021.01.29