1 | # PostCSS Extend Rule [<img src="https://postcss.github.io/postcss/logo.svg" alt="PostCSS" width="90" height="90" align="right">][postcss]
|
2 |
|
3 | [![NPM Version][npm-img]][npm-url]
|
4 | [![test](https://github.com/csstools/postcss-extend-rule/actions/workflows/test.yml/badge.svg)](https://github.com/csstools/postcss-extend-rule/actions/workflows/test.yml)
|
5 | [<img alt="Discord" src="https://shields.io/badge/Discord-5865F2?logo=discord&logoColor=white">][discord]
|
6 |
|
7 | [PostCSS Extend Rule] lets you use the `@extend` at-rule and
|
8 | [Functional Selectors] in CSS, following the speculative
|
9 | [CSS Extend Rules Specification].
|
10 |
|
11 | ```pcss
|
12 | %thick-border {
|
13 | border: thick dotted red;
|
14 | }
|
15 |
|
16 | .serious-modal {
|
17 | font-style: normal;
|
18 | font-weight: bold;
|
19 |
|
20 | @media (max-width: 240px) {
|
21 | @extend .modal:hover;
|
22 | }
|
23 | }
|
24 |
|
25 | .modal {
|
26 | @extend %thick-border;
|
27 |
|
28 | color: red;
|
29 | }
|
30 |
|
31 | .modal:hover:not(:focus) {
|
32 | outline: none;
|
33 | }
|
34 |
|
35 | /* becomes */
|
36 |
|
37 | .serious-modal {
|
38 | font-style: normal;
|
39 | font-weight: bold;
|
40 | }
|
41 |
|
42 | @media (max-width: 240px) {
|
43 | .serious-modal:not(:focus) {
|
44 | outline: none;
|
45 | }
|
46 | }
|
47 |
|
48 | .modal {
|
49 | border: thick dotted red;
|
50 | color: red;
|
51 | }
|
52 |
|
53 | .modal:hover:not(:focus) {
|
54 | outline: none;
|
55 | }
|
56 | ```
|
57 |
|
58 | ## Usage
|
59 |
|
60 | Add [PostCSS Extend Rule] to your project:
|
61 |
|
62 | ```bash
|
63 | npm install postcss postcss-extend-rule --save-dev
|
64 | ```
|
65 |
|
66 | Use **PostCSS Extend Rule** to process your CSS:
|
67 |
|
68 | ```js
|
69 | const postcssExtendRule = require('postcss-extend-rule');
|
70 |
|
71 | postcssExtendRule.process(YOUR_CSS /*, processOptions, pluginOptions */);
|
72 | ```
|
73 |
|
74 | Or use it as a [PostCSS] plugin:
|
75 |
|
76 | ```js
|
77 | const postcss = require('postcss');
|
78 | const postcssExtendRule = require('postcss-extend-rule');
|
79 |
|
80 | postcss([
|
81 | postcssExtendRule(/* pluginOptions */)
|
82 | ]).process(YOUR_CSS /*, processOptions */);
|
83 | ```
|
84 |
|
85 | **PostCSS Extend Rule** runs in all Node environments, with special instructions for:
|
86 |
|
87 | | [Node](INSTALL.md#node) | [PostCSS CLI](INSTALL.md#postcss-cli) | [Webpack](INSTALL.md#webpack) | [Create React App](INSTALL.md#create-react-app) | [Gulp](INSTALL.md#gulp) | [Grunt](INSTALL.md#grunt) |
|
88 | | --- | --- | --- | --- | --- | --- |
|
89 |
|
90 | ## Options
|
91 |
|
92 | ### name
|
93 |
|
94 | The `name` option determines the at-rule name being used to extend selectors.
|
95 | By default, this name is `extend`, meaning `@extend` rules are parsed.
|
96 |
|
97 | ```js
|
98 | postcssExtend({ name: 'postcss-extend' })
|
99 | ```
|
100 |
|
101 | If the `name` option were changed to, say, `postcss-extend`, then only
|
102 | `@postcss-extend` at-rules would be parsed.
|
103 |
|
104 | ```pcss
|
105 | main {
|
106 | @postcss-extend .some-rule;
|
107 | }
|
108 | ```
|
109 |
|
110 | ### onFunctionalSelector
|
111 |
|
112 | The `onFunctionalSelector` option determines how functional selectors should be
|
113 | handled. Its options are:
|
114 |
|
115 | - `remove` (default) removes any functional selector
|
116 | - `ignore` ignores any functional selector and moves on
|
117 | - `warn` warns the user whenever it encounters a functional selector
|
118 | - `throw` throws an error if ever it encounters a functional selector
|
119 |
|
120 | ```js
|
121 | postcssExtend({ onFunctionalSelector: 'remove' /* default */ })
|
122 | ```
|
123 |
|
124 | ```pcss
|
125 | %this-will-be-removed {}
|
126 | ```
|
127 |
|
128 | ### onRecursiveExtend
|
129 |
|
130 | The `onRecursiveExtend` option determines how recursive extend at-rules should
|
131 | be handled. Its options are:
|
132 |
|
133 | - `remove` (default) removes any recursive extend at-rules
|
134 | - `ignore` ignores any recursive extend at-rules and moves on
|
135 | - `warn` warns the user whenever it encounters a recursive extend at-rules
|
136 | - `throw` throws an error if ever it encounters a recursive extend at-rules
|
137 |
|
138 | ```js
|
139 | postcssExtend({ onRecursiveExtend: 'remove' /* default */ })
|
140 | ```
|
141 |
|
142 | ```pcss
|
143 | .this-will-not-extend-itself {
|
144 | @extend .this-will-not-extend-itself;
|
145 | }
|
146 | ```
|
147 |
|
148 | ### onUnusedExtend
|
149 |
|
150 | The `onUnusedExtend` option determines how an unused extend at-rule should be
|
151 | handled. Its options are:
|
152 |
|
153 | - `remove` (default) removes any unused extend at-rule
|
154 | - `ignore` ignores any unused extend at-rule and moves on
|
155 | - `warn` warns the user whenever it encounters an unused extend at-rule
|
156 | - `throw` throws an error if ever it encounters an unused extend at-rule
|
157 |
|
158 | ```js
|
159 | postcssExtend({ onUnusedExtend: 'remove' /* default */ })
|
160 | ```
|
161 |
|
162 | ```pcss
|
163 | main {
|
164 | @extend .this-selector-does-not-exist-and-will-be-removed;
|
165 | }
|
166 | ```
|
167 |
|
168 | [git-img]: https://img.shields.io/badge/support-chat-blue.svg
|
169 | [discord]: https://discord.gg/bUadyRwkJS
|
170 | [npm-img]: https://img.shields.io/npm/v/postcss-extend-rule.svg
|
171 | [npm-url]: https://www.npmjs.com/package/postcss-extend-rule
|
172 |
|
173 | [CSS Extend Rules Specification]: https://jonathantneal.github.io/specs/css-extend-rule/
|
174 | [Functional Selectors]: https://jonathantneal.github.io/specs/css-extend-rule/#functional-selector
|
175 | [PostCSS]: https://github.com/postcss/postcss
|
176 | [PostCSS Extend Rule]: https://github.com/csstools/postcss-extend-rule
|