Container Queries in Web Components

Container Queries are one of the most anticipated new features in CSS. I recently got a chance to play with them a bit and take the new syntax for a spin.

I came up with this demo of a book store. Each of the books is draggable and can be moved to one of three sections, with varying available space. Depending on where it is placed, different styles will be applied to the book. The full source code is up on Codepen. Here’s how it looks:

This demo currently only works in Chrome Canary. Download the latest version, then enable Container Queries under chrome://flags to see them in action.

Here’s what’s going on

Each of these books is a custom element, or “web component”. They each contain a cover image, a title and an author. In markup they look like this:

<book-element color="#ba423d">
<img slot="cover" src="/books/1984.avif" alt="cover by shepard fairey" />
<span slot="title">1984</span>
<span slot="author">George Orwell</span>

This then gets applied to a template which defines the internal Shadow DOM of the component. The <slot> elements in there will get replaced by the actual content we’re passing in.

<template id="book-template">
<article class="book">
<div class="front">
<slot name="cover"></slot>
<div class="meta">
<h2 class="title"><slot name="title"></slot></h2>
<p class="author"><slot name="author"></slot></p>

Alright, nothing too fancy yet, just some basic structure.

The magic happens when we apply some internal styling to this. Everything inside that <style> tag will be scoped to the component - and since styles can not leak out of the shadow DOM and we can’t (easily) style its contents from the outside, we have real component encapsulation.

Container Queries are one of the last few missing puzzle pieces in component-driven design. They enable us to give components intrinsic styles, meaning they can adapt themselves to whatever surroundings they are placed in.

The new key property there is container-type - it lets us define an element as a container to compare container queries against. A value of inline-size indicates that this container will response to “dimensional queries on the inline axis”, meaning we will apply different styles based on its width.

We can also give our container a name using the container-name property. It is optional in this example, but you can think of it in the same way that grid-area lets you define arbitrary names to use as references in your code later.

<template id="book-template">
/* Use Web Component Root as the Layout Container */
:host {
display: block;
container-type: inline-size;
container-name: book;

In the bookstore demo, I created three variants that depend on the width of the component’s :host (which translates to the <book-element> itself). I’ve omitted some of the styling for brevity here, but this part is where we define the multi-column or 3D book styles.

/* Small Variant: Simple Cover + Title */
@container (max-width: 199px) {
.book {
padding: 0;
/* Medium Variant: Multi-Column, with Author */
@container (min-width: 200px) and (max-width: 399px) {
.book {
display: grid;
grid-template-columns: 1fr 1fr;
gap: 1rem;
/* Large Variant: 3D Perspective */
@container (min-width: 400px) {
.book {
position: relative;
transform-style: preserve-3d;
transform: rotateY(-25deg);

By adding Dragula.js to enable drag-and-drop functionality, we can then move the individual components around. As soon as they’re moved to a different section in the DOM, its internal styles are re-calculated to match the new environment, and the corresponding CSS block is applied. Magic!

The Bento Box Idea

Now theoretically, we could have achieved a similar effect by using the cascade itself. We could for example apply the 3D styles to all .books inside .stage. But that would have some problems:

  • it wouldn’t be responsive - if .stage ever gets too narrow, it would break
  • it would create an unwanted dependency context between parent and child
  • it would break component encapsulation and mix layout with content styles

It’s generally a good idea in CSS to separate “layout” from “content” components and let each handle their own specific areas of responsibility. I like to think of Japanese bento boxes as a metaphor for this: a container divided into specific sections that can be filled with anything.

For example, the layout for our bookstore looks like this:

layout schema for the bookstore with three main content sections

It’s a grid divided into three sections, the middle one containing a nested flexible grid itself.

<div class="layout">
<div class="stage"></div>
<main class="content">
<ul class="itemlist"></ul>
<div class="cart"></div>
/* main layout sections */
padding: var(--spacing);

/* nested sub-grid */
.itemlist {
display: grid;
grid-template-columns: repeat(auto-fill, minmax(200px, 1fr));
gap: var(--spacing);

/* desktop layout */
@media (min-width: 1024px) {
.layout {
height: 100vh;
grid-template-columns: 480px 1fr 130px;

The parts of the layout are only concerned with the alignment and dimensions of boxes. They have no effect whatsoever on their children other than giving them a certain amount of space to fill. Just like a bento box, it doesn’t care what we put into it, so we could easily re-use the layout for a completely different product. It is content-agnostic.

That’s why Container Queries pair so well with Web Components. They both offer ways to encapsulate logic to build smart, independent building blocks. Once they’re defined, they can be used anywhere.

Container Queries bring us one step closer to “Intrinsic Layouts” and a future of truly independent, component-driven design. Exciting stuff ahead!

Further Reading


What’s this?
  1. Pablo Lara H
    Container Queries in Web Components by Max Böck @mxbck #containerqueries #css #ChromeCanary…
  2. Max Böck
    please do! container queries are uncharted territory, so very interested in what you have to say about them ;)
  3. Max Böck
    also looking forward to your upcoming course 😉
  4. Sara Soueidan
    Thank youuuu Max 😃
  5. Juan
    many awesome posts on container queries lately. Add this one by Max to the list.
Show All Webmentions (63)
  1. Vadim Makeev 🚜
    That’s a nice combo! Thank you for mixing CQ and WC together, the whole case feels stronger because of that. You also haven’t mentioned Sass or any other preprocessor, but there’s > * + * nested selector, which might be a bit confusing.
  2. Max Böck
    True, it's not necessary there. I'll remove it. 👍
  3. HN Front Page
    CSS Container Queries in Web Components L:… C:…
  4. Hacker News
    CSS Container Queries in Web Components:… Comments:…
  5. Winson Tang
    CSS Container Queries in Web Components…
  6. yosh
    Yesssss, container queries! It's been a few years since I was working on CSS tooling and reusable components, but I remember wanting this so badly. Not being able to define layouts which adapt to their available space on-screen makes it so hard to reuse…
  7. Tweet Snipper
    CSS Container Queries in Web Components…
  8. HackerNewsTop10
    CSS Container Queries in Web Components Link:… Comments:…
  9. Angsuman's Server
    CSS Container Queries in Web Components…
  10. Hacker News
    CSS Container Queries in Web Components…
  11. James Lau
    Container Queries concept demo by @mxbck.…
  12. Hacker News 20
    CSS Container Queries in Web Components… (…)
  13. Adactio Links
    Container Queries in Web Components | Max Böck…
  14. WebコンポーネントのCSSコンテナクエリ…
  15. Hacker News 50
    CSS Container Queries in Web Components… (…)
  16. Jorge Cisneros
    CSS Container Queries in Web Components…
  17. Ryan Bell
    Container queries bring us one step closer to native intrinsic layouts…
  18. Zoltán Cserei
    container queries are going to be awesome…
  19. Luis Orduz
    Could come in handy.…
  20. Friday Front-End
    Container Queries in Web Components, by @mxbck…
  21. 雑u Bot
    CSS Container Queries in Web Components…
  22. FullStack Bulletin
    Container Queries in Web Components…
  23. Silvestar Bistrović
    Max Böck explores Container Queries and shares the process of creating a book store demo.… via @mxbck #ui #uidev #css #webdev #frontend
  24. ♟️Eduardo
    "Las Container Queries son una de las nuevas funciones más esperadas de #CSS. Recientemente tuve la oportunidad de jugar un poco con ellos para probar la nueva sintaxis."…
  25. Scott Jehl
    This pattern of using :host to set up web component elements to support container query CSS is really nice. Great idea, @mxbck!… (found via @css)
  26. Sara Soueidan
    #CSS Container Queries in Web Components… — We're yet another step closer to a more modularized Web, and the possibilities are yet to be explored. ✨
  27. Phuoc Nguyen
    Container Queries in Web Components… Thanks for sharing that useful post, @mxbck 👍 #webdev #FrontEnd #webcomponent
  28. Brian Perry
    Cool example of using container queries in a web component. Also hard to believe this combination of things is possible now (even if only in Chrome Canary)…
  29. martinkosh
    Container Queries in Web Components… #Programming #developer #web
  30. Sean O
    Ooo would be really neat if each cover had a container-responsive design to optimize readability at smaller sizes. Future of book design?
  31. Lucijan Blagonić
    Container Queries in Web Components… — the demo is so slick and a great example for container queries! 👏 Well done @mxbck
  32. Sakito
    このCSS Container Queriesの例はいいユースケースの例だった。 Container Queries in Web Components…
  33. Steve Perry
    Exciting times ahead with container queries. Looking forward to having a play with them and web components when I get chance.…
  34. Frontend Daily 🚀
    Container Queries in Web Components:… (Here's a Chrome-only demo showing container queries in action.)
  35. Imabit Inc
    #CSS #Automated | Container Queries in Web Components…
  36. Front-End Front
    Container Queries in Web Components…
  37. Chris Ashton
    Nice summary of CSS container queries, with real world example:…
  38. Выражения от контейнера в веб-компонентах. Макс Бёк показывает, как можно будет удобно применять директиву @​container внутри изолированного Shadow DOM веб-компонентов.…
  39. Daniel
    A collection of cool links, ideas, and news that I've seen in the past few days: the :not() CSS pseudo selector accepts a complete list of selectors. We can do something like :not(h1, h2, #main) as we have for the :is selector CSS inset is now fully supported. This means we can have shorthands as inset: 4px 8px; instead of top: 4px ; right: 8px; we can emulate the dark mode and reduced motion in Chrome Dev Tools. More details here. in PHP you can use debug_backtrace() to print the full stack trace as we have in javascript the console.trace seen in the CSS Tricks newsletter a great example for the Container Queries made by Max Böck. Impressive stuff. That's all folks! See you the next time! I hope you have enjoyed this article and if you would like to get more articles about React and frontend development you can always sign up for my email list. Newsletter subscribe:
    Container Queries in Web Components…
  41. Frontend Dogma
    Container Queries in Web Components, by @mxbck:…
  42. Snook
    Really like this demo of Container Queries with web components.…
  43. Joulse
    Container Queries in Web Components…
  44. Mazik Solutions
    Container Queries in Web Components…
  45. Alex Devero
    Container Queries in Web Components… #webdesign #css #webdev
  46. Hidde
    I also encourage folks to look into CSS's feature. Some ace upcoming features are very CSS mental modal, less Tailwind mental modal. Cascade Layers, conflict resolution in the browser:… Container Queries, component-based adaptiveness…
  47. Maarten Hus
    Sometimes I wonder if CSS is becoming to complex: cascade layers and container queries are good examples of this. Perhaps this is part of the appeal of tailwind. I think back-end’ers used to know 80 percent of the CSS API because it was simple, it is quickly becoming very vast.
  48. S.I.D.D.H
    Cascade layer is already included in Tailwind since the v2 if I’m not mistaken. I’m a huge Tailwind fan myself yet I’m a CSS lover first. Tailwind is a very nice way to act both on the CSS level (with the @apply command) and HTML to apply smooth changes to your page
  49. Elliott Marquez
    This article is excellent I'm so excited about Container Queries and WCs
  50. Update your articles and demos my friends! Container queries are coming 🥳
  51. @NikkiMK it's almost here...
  52. Burton Smith
    Being able to encapsulate component behavior with container queries is going to be huge for #webcomponents and their potability! You can build great experiences into your components no matter where they get placed in apps.
  53. var(—alex-wilson)
  54. たいち ひ… コンテナクエリ と Web Components のコンボマジでやばそう 🤯🤯🤯