You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

194 lines
4.1 KiB

2 years ago
# PostCSS Nesting [<img src="https://postcss.github.io/postcss/logo.svg" alt="PostCSS" width="90" height="90" align="right">][postcss]
[![NPM Version][npm-img]][npm-url]
[![CSS Standard Status][css-img]][css-url]
[<img alt="Discord" src="https://shields.io/badge/Discord-5865F2?logo=discord&logoColor=white">][discord]
[PostCSS Nesting] lets you nest style rules inside each other, following the
[CSS Nesting] specification. If you want nested rules the same way [Sass] works
you might want to use [PostCSS Nested] instead.
```pcss
a, b {
color: red;
& c, & d {
color: white;
}
}
/* becomes */
a, b {
color: red;
}
a c, a d, b c, b d {
color: white;
}
```
## Usage
Add [PostCSS Nesting] to your project:
```bash
npm install postcss-nesting --save-dev
```
Use [PostCSS Nesting] to process your CSS:
```js
import postcssNesting from 'postcss-nesting';
postcssNesting.process(YOUR_CSS /*, processOptions, pluginOptions */);
```
Or use it as a [PostCSS] plugin:
```js
import postcss from 'postcss';
import postcssNesting from 'postcss-nesting';
postcss([
postcssNesting(/* pluginOptions */)
]).process(YOUR_CSS /*, processOptions */);
```
[PostCSS Nesting] runs in all Node environments, with special instructions for:
| [Node](INSTALL.md#node) | [Webpack](INSTALL.md#webpack) | [Create React App](INSTALL.md#create-react-app) | [Gulp](INSTALL.md#gulp) | [Grunt](INSTALL.md#grunt) |
| --- | --- | --- | --- | --- |
### Deno
You can also use [PostCSS Nesting] on [Deno]:
```js
import postcss from "https://deno.land/x/postcss/mod.js";
import postcssNesting from "https://cdn.jsdelivr.net/npm/postcss-nesting@10/mod.js";
await postcss([postcssNesting]).process(YOUR_CSS /*, processOptions */);
```
## Options
### noIsPseudoSelector
#### Specificity
Before :
```css
#alpha,
.beta {
&:hover {
order: 1;
}
}
```
After **without** the option :
```js
postcssNesting()
```
```css
:is(#alpha,.beta):hover {
order: 1;
}
```
_`.beta:hover` has specificity as if `.beta` where an id selector, matching the specification._
[specificity: 1, 1, 0](https://polypane.app/css-specificity-calculator/#selector=%3Ais(%23alpha%2C.beta)%3Ahover)
After **with** the option :
```js
postcssNesting({
noIsPseudoSelector: true
})
```
```css
#alpha:hover, .beta:hover {
order: 1;
}
```
_`.beta:hover` has specificity as if `.beta` where a class selector, conflicting with the specification._
[specificity: 0, 2, 0](https://polypane.app/css-specificity-calculator/#selector=.beta%3Ahover)
#### Complex selectors
Before :
```css
.alpha > .beta {
& + & {
order: 2;
}
}
```
After **without** the option :
```js
postcssNesting()
```
```css
:is(.alpha > .beta) + :is(.alpha > .beta) {
order: 2;
}
```
After **with** the option :
```js
postcssNesting({
noIsPseudoSelector: true
})
```
```css
.alpha > .beta + .alpha > .beta {
order: 2;
}
```
_this is a different selector than expected as `.beta + .alpha` matches `.beta` followed by `.alpha`._<br>
_avoid these cases when you disable `:is()`_<br>
_writing the selector without nesting is advised here_
```css
/* without nesting */
.alpha > .beta + .beta {
order: 2;
}
```
### ⚠ Spec disclaimer
The [CSS Nesting Module] spec states on nesting that "Declarations occuring after a nested rule are invalid and ignored.".
While we think it makes sense on browsers, enforcing this at the plugin level introduces several constrains that would
interfere with PostCSS' plugin nature such as with `@mixin`
[css-img]: https://cssdb.org/images/badges/nesting-rules.svg
[css-url]: https://cssdb.org/#nesting-rules
[discord]: https://discord.gg/bUadyRwkJS
[npm-img]: https://img.shields.io/npm/v/postcss-nesting.svg
[npm-url]: https://www.npmjs.com/package/postcss-nesting
[CSS Nesting]: https://drafts.csswg.org/css-nesting-1/
[PostCSS]: https://github.com/postcss/postcss
[PostCSS Nesting]: https://github.com/csstools/postcss-plugins/tree/main/plugins/postcss-nesting
[Deno]: https://deno.land/x/postcss_nesting
[PostCSS Nested]: https://github.com/postcss/postcss-nested
[Sass]: https://sass-lang.com/
[CSS Nesting Module]: https://www.w3.org/TR/css-nesting-1/