postcss-nesting

PostCSS Nesting

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.

a, b {
	color: red;

	/* "&" comes first */
	& c, & d {
		color: white;
	}

	/* "&" comes later, requiring "@nest" */
	@nest e & {
		color: yellow;
	}
}

/* becomes */

a, b {
	color: red;
}

a c, a d, b c, b d {
	color: white;
}

e a, e b {
	color: yellow;
}

Usage

Add PostCSS Nesting to your project:

npm install postcss-nesting --save-dev

Use PostCSS Nesting as a PostCSS plugin:

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	Webpack	Create React App	Gulp	Grunt

Deno

You can also use PostCSS Nesting on Deno:

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 :

#alpha,
.beta {
	&:hover {
		order: 1;
	}
}

After without the option :

postcssNesting()

:is(#alpha,.beta):hover {
	order: 1;
}

.beta:hover has specificity as if .beta where an id selector, matching the specification.

specificity: 1, 1, 0

After with the option :

postcssNesting({
	noIsPseudoSelector: true
})

#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

Complex selectors

Before :

.alpha > .beta {
	& + & {
		order: 2;
	}
}

After without the option :

postcssNesting()

:is(.alpha > .beta) + :is(.alpha > .beta) {
	order: 2;
}

After with the option :

postcssNesting({
	noIsPseudoSelector: true
})

.alpha > .beta + .alpha > .beta {
	order: 2;
}

this is a different selector than expected as .beta + .alpha matches .beta followed by .alpha.
avoid these cases when you disable :is()
writing the selector without nesting is advised here

/* without nesting */
.alpha > .beta + .beta {
	order: 2;
}

⚠️ Spec disclaimer

The CSS Nesting Module spec states on nesting that "Declarations occurring after a nested rule are invalid and ignored.". While we think it makes sense on browsers, enforcing this at the plugin level introduces several constraints that would interfere with PostCSS' plugin nature such as with @mixin