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 of a container. This is similar to a @media query, except that it evaluates against a container instead of the viewport.

🤔 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/cqfill.iife.min.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.



🔥 Like what you see? Want to stay in the loop? Here's how:

About the author

Bramus is a Freelance Web Developer from Belgium. 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 …)

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.