A first look at container-query-polyfill, a polyfill for CSS Container Queries

Surma has been working on container-query-polyfill, a lightweight polyfill for CSS Container Queries. Let’s take a look at how it works and how it differs from cqfill


🤔 Container Queries?

Container Queries allow authors to style elements according to the size or appearance of a container. For size based container queries this is similar to a @media query, except that it will evaluate against the size of a parent container instead of the viewport.

For style based container queries you conditionally apply styles based on the calculated value of another CSS property.

🤔 Polyfill?

A polyfill is a piece of code (or plugin) that provides the technology that you, the developer, expect the browser to provide natively — What is a Polyfill?



Unlike cqfillwhich was covered here before— this Polyfill for Container Queries:

  • Does not require you to declare a separate Custom Property --css-contain that duplicates the value of the contain property
  • Does not require you to duplicate your @container rule into a @media rule
  • Parses the newer Container Queries Syntax that uses the container-type + container-name properties (shorthanded to container)

Because of this, the polyfill is a drop-in piece of code that will automagically do its thing 🙂

It transpiles CSS code on the client-side and implements Container Query functionality using ResizeObserver and MutationObserver.

Additionally this polyfill does not rely on requestAnimationFrame, which makes it more performant.


Installation + Usage

Installation per NPM:

npm i container-query-polyfill

To use, import the polyfill when no support for container queries is detected:

const supportsContainerQueries = "container" in document.documentElement.style;
if (!supportsContainerQueries) {

Alternatively, load it via a (self-invoking) remote script:

<script src="https://unpkg.com/container-query-polyfill/dist/container-query-polyfill.modern.js"></script>

Supported are all modern browsers: Chrome 88+, Firefox 78+, and Safari 14+.

👨‍🏫 Unfamiliar with the syntax of CSS Container Queries itself? No worries, you can learn CSS Container Queries here.



I’ve updated my original Container Queries Demo to include this polyfill. Works like a charm:

See the Pen
CSS Container Queries Demo
by Bramus (@bramus)
on CodePen.



Do note that this polyfill comes with a few limitations:

  • Only a subset of queries is supported for now. Specifically, only min-width, max-width, min-height and max-height are supported.
  • Only top-level Container Queries are supported — no nesting of CQs in other Media Queries.
  • Container query thresholds can only be specified using pixels.

These limitations are the result of a design choice:

My aim is to make the polyfill work correctly for the majority of use-cases, but cut corners where possible to keep the polyfill simple(-ish), small and efficient.

Sounds totally reasonable.



Published by Bramus!

Bramus is a frontend web developer from Belgium, working as a Chrome Developer Relations Engineer at Google. From the moment he discovered view-source at the age of 14 (way back in 1997), he fell in love with the web and has been tinkering with it ever since (more …)

Unless noted otherwise, the contents of this post are licensed under the Creative Commons Attribution 4.0 License and code samples are licensed under the MIT License

Join the Conversation


    1. Thanks for reporting this. The file naming indeed got updated with the release of version 1.0. I have updated the post and the demo code to use the correct path.

Leave a comment

Your email address will not be published. Required fields are marked *

This site uses Akismet to reduce spam. Learn how your comment data is processed.