Skip to content


Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time
January 27, 2019 15:06
September 18, 2017 12:45
January 27, 2019 17:16
July 15, 2017 19:19
January 27, 2019 03:47
January 27, 2019 17:14
January 27, 2019 03:47
February 15, 2017 22:14
January 27, 2019 03:47
January 27, 2019 03:47
January 27, 2019 03:47
January 27, 2019 17:16
January 27, 2019 03:58

Container Query

npm version build Coverage Status Greenkeeper badge


A PostCSS plugin and Javascript runtime combination, which allows you to write container queries in your CSS the same way you would write media queries.

🕶 Uses Resize Observer: Uses the native ResizeObserver implentation when available, and falls back to a polyfill to detect size changes. If you use Chrome, you can test how performant the plugin is with the native implementation. (Shipped in v64.)

📦 Bundler Support: Built with bundlers in mind, like Parcel, webpack and Browserify.

🎲 Component Support: Built with component-based libraries in mind, like React, Vue, Ember and Angular.

📄 Intuitive Syntax: Uses at-rules, the same way @media queries do: @container (...) { ... }

🎉 Container Units: rh, rw, rmin, rmax, which are relative to the container element's width and / or height. (Same way viewport units are relative to the viewport's size.)

Cross-Browser Testing: Sponsored with ❤️ by SauceLabs.


Container queries are very similar to media queries; they allow you to apply styles to elements when certain conditions are met.

The key difference is that while media queries are relative to the viewport's size, container queries are relative to a container element's size.

Thanks to this trait, you can have multiple instances of the same container element, all of which changes its own- and its childrens' styles based on the containing element's size.

What is a Container?

A container is just an HTML element, which may (or may not) contain other elements.

You may want to think of them as "Components" (React) or "Blocks" (BEM).


The best way to understand the concept, is if you try it for yourself.

Note that because these demos are hosted on CodeSandbox, where webpack or PostCSS cannot (currently) be configured, styles are simply imported as strings and processed in the browser. (Using @zeecoder/cq-demo-utils.)

While this works for demo purposes, in a real application it is strongly recommended to process styles build-time, as later described in this documentation.


What's Next?

Ideas for Enhancement


Please consider supporting me if you like what I do on my Patreon page.

Thoughts on Design

In case you're wondering about the tool's design, here is a list of goals I had in mind with the initial implementation:

  • Should be tested,
  • Should use containers instead of elements (As opposed to other "element-query" libraries.),
  • Should use a media query-like syntax so that it's familiar and easy to use,
  • Should uses PostCSS for preprocessing, instead of having a runtime parser,
  • Should be easy enough to use, but a transpiling step would be assumed (Due to the reason above.),
  • Should use ES modules, so it plays nicely with bundlers (Parcel, webpack Browserify, etc.) and with Component-oriented UI libraries (React, Vue, etc.),
  • Should work best with component naming methodologies, like BEM or SUIT, but should also work without them.


The WICG dived into 2018 with renewed effort to make native Container Queries a reality in browsers.

If you're interested in how things are progressing, please feel free to visit the following links, where the disussions are happening:



If you like the idea of container queries, but are not particularly convinced by this solution, then I encourage you to look at these alternatives: