https://github.com/apostrophecms/postcss-viewport-to-container-toggle
https://github.com/apostrophecms/postcss-viewport-to-container-toggle
Last synced: 8 months ago
JSON representation
- Host: GitHub
- URL: https://github.com/apostrophecms/postcss-viewport-to-container-toggle
- Owner: apostrophecms
- Created: 2024-10-29T08:18:34.000Z (over 1 year ago)
- Default Branch: main
- Last Pushed: 2025-08-06T16:19:57.000Z (10 months ago)
- Last Synced: 2025-10-22T18:48:39.390Z (8 months ago)
- Language: JavaScript
- Size: 64.5 KB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
Awesome Lists containing this project
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:
In mobile preview, body being a container, this block will take `50cqw` of the container:
## 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`.