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

~

🤔 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?

~

What

Unlike cqfill —which 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/dist/container-query-polyfill.modern.js"></script>

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

~

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 →