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?

~

What

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) {
  import("container-query-polyfill");
}

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.

~

Demo

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.

~

Notes

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.

~

container-query-polyfill

🔥 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.