PostCSS Extend Rule

PostCSS Extend Rule lets you use the @extend at-rule and Functional Selectors in CSS, following the speculative CSS Extend Rules Specification.

1%thick-border {
2  border: thick dotted red;
3}
4
5.serious-modal {
6  font-style: normal;
7  font-weight: bold;
8
9  @media (max-width: 240px) {
10    @extend .modal:hover;
11  }
12}
13
14.modal {
15  @extend %thick-border;
16
17  color: red;
18}
19
20.modal:hover:not(:focus) {
21  outline: none;
22}
23
24/* becomes */
25
26.serious-modal {
27  font-style: normal;
28  font-weight: bold;
29}
30
31@media (max-width: 240px) {
32  .serious-modal:not(:focus) {
33    outline: none;
34  }
35}
36
37.modal {
38  border: thick dotted red;
39  color: red;
40}
41
42.modal:hover:not(:focus) {
43  outline: none;
44}

Usage

Add PostCSS Extend Rule to your project:

1npm install postcss postcss-extend-rule --save-dev

Use PostCSS Extend Rule to process your CSS:

1const postcssExtendRule = require('postcss-extend-rule');
2
3postcssExtendRule.process(YOUR_CSS /*, processOptions, pluginOptions */);

Or use it as a PostCSS plugin:

1const postcss = require('postcss');
2const postcssExtendRule = require('postcss-extend-rule');
3
4postcss([
5  postcssExtendRule(/* pluginOptions */)
6]).process(YOUR_CSS /*, processOptions */);

PostCSS Extend Rule runs in all Node environments, with special instructions for:

Node	PostCSS CLI	Webpack	Create React App	Gulp	Grunt

Options

name

The name option determines the at-rule name being used to extend selectors. By default, this name is extend, meaning @extend rules are parsed.

1postcssExtend({ name: 'postcss-extend' })

If the name option were changed to, say, postcss-extend, then only @postcss-extend at-rules would be parsed.

1main {
2  @postcss-extend .some-rule;
3}

onFunctionalSelector

The onFunctionalSelector option determines how functional selectors should be handled. Its options are:

• remove (default) removes any functional selector
• ignore ignores any functional selector and moves on
• warn warns the user whenever it encounters a functional selector
• throw throws an error if ever it encounters a functional selector

1postcssExtend({ onFunctionalSelector: 'remove' /* default */ })

1%this-will-be-removed {}

onRecursiveExtend

The onRecursiveExtend option determines how recursive extend at-rules should be handled. Its options are:

• remove (default) removes any recursive extend at-rules
• ignore ignores any recursive extend at-rules and moves on
• warn warns the user whenever it encounters a recursive extend at-rules
• throw throws an error if ever it encounters a recursive extend at-rules

1postcssExtend({ onRecursiveExtend: 'remove' /* default */ })

1.this-will-not-extend-itself {
2  @extend .this-will-not-extend-itself;
3}

onUnusedExtend

The onUnusedExtend option determines how an unused extend at-rule should be handled. Its options are:

• remove (default) removes any unused extend at-rule
• ignore ignores any unused extend at-rule and moves on
• warn warns the user whenever it encounters an unused extend at-rule
• throw throws an error if ever it encounters an unused extend at-rule

1postcssExtend({ onUnusedExtend: 'remove' /* default */ })

1main {
2  @extend .this-selector-does-not-exist-and-will-be-removed;
3}