How to use container queries now  |  Blog  |  web.dev

elements to be elements instead:

  
  ...

In most situations, you can just use the element without any customization, but if you do need to customize it, the following options are available:

• Custom breakpoint sizes: This code uses a set of default breakpoint class names and min-width sizes, but you change these defaults to be whatever you like. You can also override these values on a per-element basis using the breakpoints attribute.
• Named containers: This code also supports named containers by passing a name attribute. This can be important if you need to nest container elements. See the limitations section for more details.

Here is an example that sets both of these configuration options:

Finally, when bundling this code, make sure you use feature detection and dynamic import() to only load it if the browser doesn't support container queries.

if (!CSS.supports('container-type: inline-size')) {
  import('./path/to/responsive-container.js');
}

Step 3: add fallback styles to your CSS

The last step in this strategy is to add fallback styles for browsers that don't recognize the styles defined in the @container rules. Do this by duplicating those rules using the breakpoint classes that get set on the elements.

Continuing with the .photo-gallery example from before, the fallback styles for the two @container rules might look like this:

/* Container query styles for the `MD` breakpoint. */
@container (min-width: 768px) {
  .photo-gallery {
    grid-template-columns: 1fr 1fr;
  }
}

/* Fallback styles for the `MD` breakpoint. */
@supports not (container-type: inline-size) {
  :where(responsive-container.MD) .photo-gallery {
    grid-template-columns: 1fr 1fr;
  }
}

/* Container query styles for the `XL` breakpoint. */
@container (min-width: 1280px) {
  .photo-gallery {
    grid-template-columns: 1fr 1fr 1fr;
  }
}

/* Fallback styles for the `XL` breakpoint. */
@supports not (container-type: inline-size) {
  :where(responsive-container.XL) .photo-gallery {
    grid-template-columns: 1fr 1fr 1fr;
  }
}

In this code, for each @container rule there is an equivalent rule conditionally matching the element if the corresponding breakpoint class is present.

The portion of the selector matching the element is wrapped in a :where() functional pseudo-class selector, to keep the specificity of the fallback selector equivalent to the specificity of the original selector within the @container rule.

Each fallback rule is also wrapped in an @supports declaration. While this is not strictly necessary for the fallback to work, it means that the browser completely ignores these rules if it supports container queries, which can improve style matching performance in general. It also potentially allows build tools or CDNs to strip those declarations if they know the browser supports container queries and doesn't need those fallback styles.

The main downside of this fallback strategy is it requires you to repeat style declaration twice, which is both tedious and error prone. However, if you're using a CSS preprocessor, you can abstract that into a mixin that generates both the @container rule and the fallback code for you. Here's an example using Sass:

@use 'sass:map';

$breakpoints: (
  'SM': 512px,
  'MD': 576px,
  'LG': 1024px,
  'XL': 1280px,
);

@mixin breakpoint($breakpoint) {
  @container (min-width: #{map.get($breakpoints, $breakpoint)}) {
    @content();
  }
  @supports not (container-type: inline-size) {
    :where(responsive-container.#{$breakpoint}) & {
      @content();
    }
  }
}

Then, once you have this mixin, you could update the original .photo-gallery component styles to something like this, which eliminates the duplication entirely:

.photo-gallery {
  display: grid;
  grid-template-columns: 1fr;

  @include breakpoint('MD') {
    grid-template-columns: 1fr 1fr;
  }

  @include breakpoint('XL') {
    grid-template-columns: 1fr 1fr 1fr;
  }
}

And that's all there is to it!

Recap

So, to recap, here's how to update your code to use container queries now with a cross browser fallback.

1. Identity components that you want to style relative to their container, and update the @media rules in their CSS to use @container rules. Also (if you're not already), standardize on a set of breakpoint names to match the size conditions in your container rules.
2. Add the JavaScript that powers the custom element, and then add the element to any content areas in your page that you want your components to be relative to.
3. To support older browsers, add fallback styles to your CSS that match against the breakpoint classes that get automatically added to the elements in your HTML. Ideally use a CSS preprocessor mixin to avoid having to write the same styles twice.

The great thing about this strategy is there is a one-time setup cost, but after that it doesn't take any additional effort to add new components and define container-relative styles for them.

Seeing it in action

Probably the best way to understand how all these steps fit together is to see a demo of it in action.

This demo is an updated version of a site created in 2019 (before container queries existed) to help illustrate why container queries are essential to building truly responsive component libraries.

Since this site already had styles defined for a bunch of "responsive components", it was a perfect candidate to test out the strategy introduced here on a non-trivial site. Turns out, it was actually quite simple to update and required almost no changes to the original site styles.

You can check out the full demo source code on GitHub, and be sure to look specifically at the demo component CSS, to see how the fallback styles are defined. If you want to test out just the fallback behavior, there's a fallback-only demo that includes just that variant—even in browsers that support container queries.

Limitations and potential improvements

As mentioned at the beginning of this post, the strategy outlined here works well for the majority of use cases that developers actually care about when reaching for container queries.

That said, there are some more advanced use cases that this strategy intentionally does not attempt to support, addressed next:

Container query units

The specification for container queries defines a number of new units, that are all relative to the container's size. While potentially useful in some cases, the majority of responsive designs can likely be achieved through existing means, such as percentages or using grid or flex layouts.

That said, if you do need to use container query units, you could easily add support for them using custom properties. Specifically, by defining a custom property for each unit used on the container element, like this:

responsive-container {
  --cqw: 1cqw;
  --cqh: 1cqh;
}

And then whenever you need to access the container query units, use those properties, rather than using the unit itself:

.photo-gallery {
  font-size: calc(10 * var(--cqw));
}

Then, to support older browsers, set the values for those custom properties on the container element within the ResizeObserver callback.

class ResponsiveContainer extends HTMLElement {
  // ...
  updateBreakpoints(contentRect) {
    this.style.setProperty('--cqw', `${contentRect.width / 100}px`);
    this.style.setProperty('--cqh', `${contentRect.height / 100}px`);

    // ...
  }
}

This effectively lets you "pass" those values from JavaScript to CSS, and then you have the full power of CSS (for example, calc(), min(), max(), clamp()) to manipulate them as needed.

Logical properties and writing mode support

You may have noticed the use of inline-size rather than width in the @container declarations in some of these CSS examples. You may have also noticed the new cqi and cqb units (for inline and block sizes, respectively). These new features reflect CSS's shift to logical properties and values rather than physical or directional ones.

Unfortunately, APIs like Resize Observer still report values in width and height, so if your designs need the flexibility of logical properties, then you need to figure that out for yourself.

While it's possible to get the writing mode using something like getComputedStyle() passing in the container element, doing so has a cost, and there's not really a good way to detect if the writing mode changes.

For this reason, the best approach is for the element itself to accept a writing mode property that the site owner can set (and update) as needed. To implement this, you'd follow the same approach shown in the previous section, and swap width and height as needed.

Nested containers

The container-name property lets you give a container a name, which you can then reference in an @container rule. Named containers are useful if you have containers nested within containers and you need certain rules to only match certain containers (not just the nearest ancestor container).

The fallback strategy outlined here uses the descendant combinator to style elements matching certain breakpoint classes. This can break if you have nested containers, since any number of breakpoint classes from multiple container element ancestors could match a given component at the same time.

For example, here there are two elements wrapping the .photo-gallery component, but since the outer container is larger than the inner container, they have different breakpoint classes added.

  ...
  
    ...
    
...
  

In this example, the MD and LG class on the outer container would affect the style rules matching the .photo-gallery component, which doesn't match the behavior of container queries (since they only match against the nearest ancestor container).

To deal with this, either:

1. Make sure you always name any containers that you're nesting, and then ensure your breakpoint classes are prefixed with that container name to avoid clashes.
2. Use the child combinator instead of the descendant combinator in your fallback selectors (which is a bit more limiting).

The nested containers section of the demo site has an example of this working using named containers, along with the Sass mixin it uses in the code to generate the fallback styles for both named and unnamed @container rules.

What about browsers that don't support :where(), Custom Elements, or Resize Observer?

While these APIs may seem relatively new, they've all been supported in all browsers for more than three years, and they're all part of Baseline widely available.

So unless you have data showing that a significant portion of your site's visitors are on browsers that don't support one of these features, then there is no reason not to freely use them without a fallback.

Even then, for this specific use case, the worst that could happen is the fallback won't work for a very small percentage of your users, which means they'll see the default view rather than a view optimized for the container size.

The functionality of the site should still work, and that's what really matters.

Why not just use a container query polyfill?

CSS features are notoriously difficult to polyfill, and generally require re-implementing the brower's entire CSS parser and cascade logic in JavaScript. As a result, CSS polyfill authors have to make many tradeoffs that almost always come with numerous feature limitations as well as significant performance overhead.

For these reasons, we generally don't recommend using CSS polyfills in production, including the container-query-polyfill from Google Chrome Labs, which is no longer maintained (and was primarily intended for demo purposes).

The fallback strategy discussed here has fewer limitations, requires far less code, and will perform significantly better than any container query polyfill ever could.

Do you even need to implement a fallback for older browsers?

If you are concerned about any of the limitations mentioned here, it's probably worth asking yourself whether you actually need to implement a fallback in the first place. After all, the easiest way to avoid these limitations is to just use the feature without any fallbacks. Honestly, in many cases, that may be a perfectly reasonable choice.

According to caniuse.com, container queries are supported by 90% of global internet users, and for many people reading this post, the number is likely quite a bit higher for their user base. So it's important to keep in mind that most of your users will see the container-query version of your UI. And for the 10% of users that won't, it's not like they're going to have a broken experience. When following this strategy, in the worst case these users will see the default or "mobile" layout for some components, which is not the end of the world.

When making tradeoffs, it's a good practice to optimize for the majority of your users—rather than defaulting to a lowest-common-denominator approach that gives all users a consistent, but sub-par, experience.

So before you assume that you can't use container queries due to lack of browser support, actually take the time to consider what the experience would be like if you did choose to adopt them. The tradeoff may be well worth it, even without any fallbacks.

Looking forward

Hopefully this post has convinced you that it is possible to use container queries in production now, and that you don't have to wait for years until all non-supporting browsers completely disappear.

While the strategy outlined here does require a bit of extra work, it should be simple and straightforward enough that most people can adopt it on their sites. That said, there is certainly room to make it even easier to adopt. One idea would be to consolidate a lot of the disparate parts into a single component—optimized for a specific framework or stack—that handles all of the glue work for you. If you build something like this, let us know and we can help promote it!

Lastly, beyond container queries, there are so many amazing CSS and UI features that are now interoperable across all major browser engines. As a community, let's figure out how we can actually use those features now, so our users can benefit.