postcss-custom-selectors
v8.0.1
Published
Use Custom Selectors in CSS
Downloads
23,697,841
Readme
PostCSS Custom Selectors
npm install postcss-custom-selectors --save-dev
PostCSS Custom Selectors lets you define @custom-selector
in CSS following the Custom Selectors Specification.
@custom-selector :--heading h1, h2, h3;
article :--heading + p {
margin-top: 0;
}
/* becomes */
article :is(h1, h2, h3) + p {
margin-top: 0;
}
Usage
Add PostCSS Custom Selectors to your project:
npm install postcss postcss-custom-selectors --save-dev
Use it as a PostCSS plugin:
const postcss = require('postcss');
const postcssCustomSelectors = require('postcss-custom-selectors');
postcss([
postcssCustomSelectors(/* pluginOptions */)
]).process(YOUR_CSS /*, processOptions */);
Options
preserve
The preserve
option determines whether the original notation
is preserved. By default, it is not preserved.
postcssCustomSelectors({ preserve: true })
@custom-selector :--heading h1, h2, h3;
article :--heading + p {
margin-top: 0;
}
/* becomes */
@custom-selector :--heading h1, h2, h3;
article :is(h1, h2, h3) + p {
margin-top: 0;
}
article :--heading + p {
margin-top: 0;
}
Modular CSS Processing
If you're using Modular CSS such as, CSS Modules, postcss-loader
or vanilla-extract
to name a few, you'll probably
notice that custom selectors are not being resolved. This happens because each file is processed separately so
unless you import the custom selector definitions in each file, they won't be resolved.
To overcome this, we recommend using the PostCSS Global Data plugin which allows you to pass a list of files that will be globally available. The plugin won't inject any extra code in the output but will provide the context needed to resolve custom selectors.
For it to run it needs to be placed before the PostCSS Custom Selectors plugin.
const postcss = require('postcss');
const postcssCustomSelectors = require('postcss-custom-selectors');
const postcssGlobalData = require('@csstools/postcss-global-data');
postcss([
postcssGlobalData({
files: [
'path/to/your/custom-selectors.css'
]
}),
postcssCustomSelectors(/* pluginOptions */)
]).process(YOUR_CSS /*, processOptions */);