Skip to content

explainer.md

Latest commit

 

History

History
774 lines (634 loc) · 21.1 KB

explainer.md

File metadata and controls

774 lines (634 loc) · 21.1 KB
Raw

Container Query Proposal & Explainer

Authors

  • Miriam Suzanne

Participate

CSSWG Issues:

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 & block-size 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. So I'm proposing two new single-axis values for contain:

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

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

Elements with <axis>-size 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 a single axis.

Of these two values, it is clear that block-size has the fewer 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.

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 layout and size 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;
}

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

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

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, there should be a fallback akin to the Initial Containing Block which queries resolve against.

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 (width > 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. When no containment context is established, the Initial Containing Block can be used to resolve the query.

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 (width > 500px) {
  div {
    background: yellow;
  }
}

@container (width > 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:

  • physical dimensions: width / height
  • logical dimensions: inline-size / block-size

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

  • aspect-ratio
  • orientation

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?

  • inline-content-box
  • font-size
  • etc.

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 (width > 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 (width > 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 (width > 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 (width > 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 (width > 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.

Detailed design discussion & alternatives

Single-axis containment issues

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:

  • For the sake of determining auto scrollbars on ancestors, the container contributes an infinite cross-axis size (always trigger the scrollbar). This is probably the more common edge-case, but in many cases auto-scrollbars imply an element has containable size on the cross-axis -- so authors could avoid this by using 2D size containment in those cases?
  • For the sake of resolving percentage-padding on the contained axis, always resolve to auto. This seems to be the existing first-pass behavior in many cases where an element has unknown size. Another option would be to drop block-size from the proposal.

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

Implicit vs explicit containers

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 (width > 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:

  • Explicitly targeted queries are less modular, so components would not be able to query whatever space they happen to be in.
  • It adds potential confusion about what selectors are allowed in the block -- since authors would not be able to style the container itself.

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:

  • Establishes its own containment context, and
  • Establishes its own selector scope

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 @-rule syntax matches more closely with existing conditional rules, and builds on existing query-list syntax.
  • It's likely that a responsive component will have multiple moving parts, and each might require unique selectors based on the same query. These can be grouped in an @-rule.
  • We avoid the issues mentioned above with having an explicit selector attached to the query.

I also think the syntax can lead to confusion. It's not immediately clear what these different selectors would mean:

:container(width < 40em) {
  font-size: small;
}
.media-object:container(width < 40em) {
  font-size: small;
}
:container(width < 40em) .media-object {
  font-size: small;
}

Other questions to explore

  • Is it possible to apply containment within a container query? In what cases might that lead to cyclic dependencies?
  • Will a default root fallback container feel like expected behavior, or should we require explicit containment in order to match queries?
  • Are there special considerations required for a shadow-DOM @container to resolve queries against contained host element?

Stakeholder Feedback / Opposition

  • Chromium : Positive -- Google was involved in developing this proposal
  • Gecko : No signals
  • Webkit : No signals

References & acknowledgements

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

Thanks also for valuable feedback and advice from:

  • Adam Argyle
  • Amelia Bellamy-Royds
  • Anders Hartvoll Ruud
  • Chris Coyier
  • Christopher Kirk-Nielsen
  • Eric Portis
  • Ethan Marcotte
  • Florian Rivoal
  • Geoff Graham
  • Gregory Wild-Smith
  • Ian Kilpatrick
  • Jen Simmons
  • Martin Auswöger
  • Martine Dowden
  • Mike Riethmuller
  • Morten Stenshorne
  • Nicole Sullivan
  • Rune Lillesveen
  • Scott Jehl
  • Scott Kellum
  • Tab Atkins
  • Theresa O’Connor
  • Una Kravets