# shadow-container-query-polyfill

> *This repo is based on https://github.com/GoogleChromeLabs/container-query-polyfill with the added enhancement for shadow dom/web components.*

Latest version **1.1.8** (published 2023-09-29) · Apache-2.0 license · 0 weekly downloads

## Install

```sh
npm install shadow-container-query-polyfill
pnpm add shadow-container-query-polyfill
yarn add shadow-container-query-polyfill
bun add shadow-container-query-polyfill
```

## Health

**Score 20/100 (F)** — status: abandoned.

Positive: esm support; no vulnerabilities.

Warnings: low downloads; no types.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 1.1.8 |
| Published | 2023-09-29 |
| First published | 2022-11-10 |
| Weekly downloads | 0 |
| License | Apache-2.0 |
| TypeScript types | none |
| Module format | ESM |
| Dependencies | 0 |
| Unpacked size | 48.1 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 9 |
| Maintainers | marshal27 |

## Links

- npm: https://www.npmjs.com/package/shadow-container-query-polyfill
- Repository: https://github.com/Marshal27/shadow-container-query-polyfill
- Homepage: https://github.com/Marshal27/shadow-container-query-polyfill#readme
- Issues: https://github.com/Marshal27/shadow-container-query-polyfill/issues
- npm.io page: https://npm.io/package/shadow-container-query-polyfill

## Recent versions

- 1.1.8 (latest) — 2023-09-29
- 1.1.7 — 2023-01-05
- 1.1.6 — 2022-12-08
- 1.1.5 — 2022-11-25
- 1.1.3 — 2022-11-22
- 1.1.2 — 2022-11-14
- 1.1.1 — 2022-11-13
- 1.1.0 — 2022-11-10
- 1.0.0 — 2022-11-10

## README

# Shadow Container Query Polyfill

*This repo is based on https://github.com/GoogleChromeLabs/container-query-polyfill with the added enhancement for shadow dom/web components.*

If you find this work helpful please consider buying me a coffee.
<br/>
<a href="https://www.buymeacoffee.com/marshal27" target="_blank"><img src="https://cdn.buymeacoffee.com/buttons/default-orange.png" alt="Buy Me A Coffee" height="41" width="174"></a>
____________________________

A small (9 kB compressed) polyfill for CSS Container Queries using [`ResizeObserver`](https://developer.mozilla.org/en-US/docs/Web/API/ResizeObserver) and [`MutationObserver`](https://developer.mozilla.org/en-US/docs/Web/API/MutationObserver) supporting the full [`@container`](https://drafts.csswg.org/css-contain-3/) query syntax:

- Discrete queries (`width: 300` and `min-width: 300px`)
- Range queries (`200px < width < 400px` and `width < 400px`)
- Container relative length units (`cqw`, `cqh`, `cqi`, `cqb`, `cqmin`, and `cqmax`) in properties and keyframes

## Browser Support

- Firefox 69+
- Chrome 79+
- Edge 79+
- Safari 13.4+

## Getting Started

### Installation

```bash
npm install --save shadow-container-query-polyfill
```

Alternatively, you can use it directly from a CDN:

```js
<script src="https://cdn.jsdelivr.net/npm/shadow-container-query-polyfill@1/dist/shadow-container-query-polyfill.modern.mjs"></script>
```

For the best user experience, it's recommended that you initially only use the polyfill for content below-the-fold and use `@supports` queries to temporarily replace it with a loading indicator until the polyfill is ready to display it:

```css
@supports not (container-type: inline-size) {
  .container,
  footer {
    display: none;
  }

  .loader {
    display: flex;
  }
}
```

You can view a more complete demo [here](https://codesandbox.io/s/smoosh-glitter-m2ub4w?file=/index.html). On sufficiently fast networks and devices, or devices that natively support Container Queries, this loading indicator will never be displayed.

> **Note**
> Keep in mind that this technique effectively limits impact on FID and CLS, potentially at the expense of LCP. You may see regressions in the latter as a result, particularly on lower end devices or in poor network conditions.

## Limitations

- **CSS first**: The polyfill currently only supports `<style>` and same-origin `<link>` elements. Inline styles via the `style` attribute or CSSOM methods are not polyfilled. Likewise, JavaScript APIs like `CSSContainerRule` are not polyfilled, and APIs like `CSS.supports()` are not monkey-patched.
- **Best effort**: Style changes that do not lead to observable DOM or layout mutations (e.g. changing `font-size` in a container without content) may not be detected, or may be detected a frame late on some browsers. [Complex sibling CSS selectors](https://github.com/GoogleChromeLabs/container-query-polyfill/issues/56) aren't supported.
- Currently, there is no support for functions like `calc(...)` in container conditions. Your contribution would be welcome!

## Supporting browsers without `:where()`

The polyfill uses the CSS [`:where()`](https://developer.mozilla.org/en-US/docs/Web/CSS/:where) pseudo-class to avoid changing the specificity of your rules. This pseudo-class is relatively new, however. If you need to support browsers without it, you will need to append the dummy `:not(container-query-polyfill)` pseudo-class to the originating element of every selector under a `@container` block:

<table>
<tr>
<td> Before </td> <td> After </td>
</tr>
<tr>
<td>

```css
@container (min-width: 200px) {
  #foo {
    /* ... */
  }

  .bar {
    /* ... */
  }

  #foo,
  .bar {
    /* ... */
  }

  ul > li {
    /* ... */
  }

  ::before {
    /* ... */
  }
}
```

</td>
<td>

```css
@container (min-width: 200px) {
  #foo:not(.container-query-polyfill) {
    /* ... */
  }

  .bar:not(.container-query-polyfill) {
    /* ... */
  }

  #foo:not(.container-query-polyfill),
  .bar:not(.container-query-polyfill) {
    /* ... */
  }

  ul > li:not(.container-query-polyfill) {
    /* ... */
  }

  :not(.container-query-polyfill)::before {
    /* ... */
  }
}
```

</td>
</tr>
</table>

This is to ensure the specificity of your rules never changes (e.g. while the polyfill is loading, or on browsers with native support for container queries). On browsers without `:where()` supports, rules without the dummy will be ignored.

## License

[Apache 2.0](LICENSE)

---
_Source: https://npm.io/package/shadow-container-query-polyfill · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._