# postcss-viewport-to-container-toggle

> A plugin for [PostCSS](https://github.com/postcss/postcss) that allows to toggle between viewport and container units based on the presence of a container data attribute.

Latest version **2.3.0** (published 2026-03-18) · MIT license · 0 weekly downloads

## Install

```sh
npm install postcss-viewport-to-container-toggle
pnpm add postcss-viewport-to-container-toggle
yarn add postcss-viewport-to-container-toggle
bun add postcss-viewport-to-container-toggle
```

## Health

**Score 45/100 (D)** — status: stable.

Positive: no vulnerabilities.

Warnings: low downloads; no types; no esm support.

## Facts

| | |
|---|---|
| Version | 2.3.0 |
| Published | 2026-03-18 |
| First published | 2024-11-07 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 0 |
| Unpacked size | 120.2 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Author | Apostrophe Technologies, Inc. |
| Maintainers | alexgilbert, boutell, romanek, bodonkey, valjed |

## Links

- npm: https://www.npmjs.com/package/postcss-viewport-to-container-toggle
- Repository: https://github.com/apostrophecms/apostrophe
- Homepage: https://github.com/apostrophecms/apostrophe/tree/main/packages/postcss-viewport-to-container-toggle#readme
- Issues: https://github.com/apostrophecms/apostrophe/issues
- npm.io page: https://npm.io/package/postcss-viewport-to-container-toggle

## Recent versions

- 2.3.0 (latest) — 2026-03-18
- 2.2.0 — 2026-01-26
- 2.1.0 — 2025-11-25
- 2.0.1 — 2025-08-06
- 2.0.0 — 2025-06-06
- 1.1.0 — 2025-03-19
- 1.0.0 — 2024-11-07

## README

# postcss-viewport-to-container-toggle 

A plugin for [PostCSS](https://github.com/postcss/postcss) that allows to toggle between viewport and container units based on the presence of a container data attribute.

## Why?

This plugin has been originally developed to allow mobile preview without using any `iframe` in order to be as close as possible to the real rendering.

For examples, let's say we have a block in our page that is taking `50vw`. 
We want in the case of the mobile preview (where body is a container), this block to take `50cqw` instead of `50vw`.

Here is what it looks like, in normal mode, our block takes `50vw` as it did before we the initial code:

![image](./images/normal.png)

In mobile preview, body being a container, this block will take `50cqw` of the container:

![image](./images/mobile.png)


## Demo

This css:

```css
.hello {
    width: 100vw;
    height: 100vh;
}
```

If you set the `modifierAttr` to `data-breakpoint-preview-mode` and `containerEl` to `body` (default), it'll be converted this way:

```css
.hello {
    width: 100vw;
    height: 100vh;
}

:where(body[data-breakpoint-preview-mode]) .hello {
    width: 100cqw;
    height: 100cqh;
}
```

The purpose being here to keep the existing behavior but to make the code work compatible for containers when body is in container mode.

Here is another examples with media queries:

```css
@media only screen and (width > 600px) and (max-width: 1000px) {
  .hello {
    top: 0;
    width: 100vw;
    height: calc(100vh - 50px);
  }
  .goodbye {
    width: 100%;
    color: #fff;
    transform: translateX(20vw);
  }
}

.toto {
  width: 100vh;
  color: white;
}
```


will become:

```css
@media only screen and (width > 600px) and (max-width: 1000px) {
  :where(body:not([data-breakpoint-preview-mode])) .hello {
    top: 0;
    width: 100vw;
    height: calc(100vh - 50px);
  }
  :where(body:not([data-breakpoint-preview-mode])) .goodbye {
    width: 100%;
    color: #fff;
    transform: translateX(20vw);
  }
}

@container (width > 600px) and (max-width: 1000px) {
  .hello {
    top: 0;
    width: 100cqw;
    height: calc(100cqh - 50px);
  }
  .goodbye {
    width: 100%;
    color: #fff;
    transform: translateX(20cqw);
  }
}

.toto {
  width: 100vh;
  color: white;
}

:where(body[data-breakpoint-preview-mode]) .toto {
  width: 100cqh;
}
```

As you can see, if body has no specific attribute, the behavior stays the same. 
When adding `data-breakpoint-preview-mode`, data in media queries are converted to container units and moved to container queries.

## Installation

```bash
npm install postcss-viewport-to-container-toggle
```

## Getting started

### Webpack

```javascript
const postcssViewportToContainerToggle = require('postcss-viewport-to-container-toggle');

{
  loader: 'postcss-loader',
  options: {
    sourceMap: true,
    postcssOptions: {
      plugins: [
        [
          postcssViewportToContainerToggle({
            modifierAttr: 'data-breakpoint-preview-mode',
            containerEl: 'body',
            debug: false
          }),
          'autoprefixer'
        ]
      ]
    }
  }
}
```

### Vite

```javascript
const postcssViewportToContainerToggle = require('postcss-viewport-to-container-toggle');

{
    css: {
      postcss: {
        plugins: [
          postcssViewportToContainerToggle({
            modifierAttr: 'data-breakpoint-preview-mode',
            containerEl: 'body',
            debug: false
          })
        ]
      }
    }
}
```

### Options

* `modifierAttr`: The attribute that will be used to toggle between viewport and container units.
* `containerEl`: The element that will be used as container. Default: `body`
* `debug`: If set to `true`, will output debug information. Default: `false`
* `transform`: A function that will be called for each media query, allowing to modify its params when creating the `container`.

---
_Source: https://npm.io/package/postcss-viewport-to-container-toggle · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._