postcss/postcss-nested

PostCSS Nested

PostCSS plugin to unwrap nested rules closer to Sass syntax.

.phone {
  &_title {
    width: 500px;
    @media (max-width: 500px) {
      width: auto;
    }
    body.is_dark & {
      color: white;
    }
  }
  img {
    display: block;
  }
}

.title {
  font-size: var(--font);

  @at-root html {
    --font: 16px;
  }
}

will be processed to:

.phone_title {
  width: 500px;
}
@media (max-width: 500px) {
  .phone_title {
    width: auto;
  }
}
body.is_dark .phone_title {
  color: white;
}
.phone img {
  display: block;
}

.title {
  font-size: var(--font);
}
html {
  --font: 16px;
}

Related plugins:

• Use postcss-current-selector after this plugin if you want to use current selector in properties or variables values.
• Use postcss-nested-ancestors before this plugin if you want to reference any ancestor element directly in your selectors with ^&.

Alternatives:

• See also postcss-nesting, which implements CSSWG draft.
• postcss-nested-props for nested properties like font-size.

  PostCSS Nested is built by Evil Martians, an American design and engineering consultancy for developer tools, AI, and cybersecurity startups.

Usage

Step 1: Install plugin:

npm install --save-dev postcss postcss-nested

Step 2: Check your project for existing PostCSS config: postcss.config.js in the project root, "postcss" section in package.json or postcss in bundle config.

If you do not use PostCSS, add it according to official docs and set this plugin in settings.

Step 3: Add the plugin to plugins list:

+import postcssNested from 'postcss-nested'
 import autoprefixer from 'autoprefixer'

 export default {
   plugins: [
+    postcssNested,
     autoprefixer
   ]
 }

Options

bubble

By default, plugin will bubble only @media, @supports, @layer, @container, and @starting-style at-rules. Use this option to add your custom at-rules to this list.

postcss([postcssNested({ bubble: ['phone'] })])

/* input */
a {
  color: white;
  @phone {
    color: black;
  }
}
/* output */
a {
  color: white;
}
@phone {
  a {
    color: black;
  }
}

unwrap

By default, plugin will unwrap only @font-face, @keyframes and @document at-rules. You can add your custom at-rules to this list by unwrap option:

postcss([postcssNested({ unwrap: ['phone'] })])

/* input */
a {
  color: white;
  @phone {
    color: black;
  }
}
/* output */
a {
  color: white;
}
@phone {
  color: black;
}

preserveEmpty

By default, plugin will strip out any empty selector generated by intermediate nesting levels. You can set preserveEmpty to true to preserve them.

.a {
  .b {
    color: black;
  }
}

Will be compiled to:

.a {
}
.a .b {
  color: black;
}

This is especially useful if you want to export the empty classes with postcss-modules.

rootRuleName

The plugin supports the SCSS custom at-rule @at-root which breaks rule blocks out of their nested position. If you want, you can choose a new custom name for this rule in your code.

postcss([postcssNested({ rootRuleName: '_escape-nesting' })])

/* input */
.a {
  color: white;
  @_escape-nesting {
    .b {
      color: black;
    }
  }
}
/* output */
.a {
  color: white;
}
.b {
  color: black;
}