[] lets you define @custom-selector in CSS following the [Custom Selectors Specification].

<example.css>

/* becomes */

<example.expect.css>

The preserve option determines whether the original notation is preserved. By default, it is not preserved.

<exportName>({ preserve: true })

<example.css>

/* becomes */

<example.preserve.expect.css>

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 [] plugin.

const postcss = require('postcss');
const <exportName> = require('<packageName>');
const postcssGlobalData = require('@csstools/postcss-global-data');

postcss([
	postcssGlobalData({
		files: [
			'path/to/your/custom-selectors.css'
		]
	}),
	<exportName>(/* pluginOptions */)
]).process(YOUR_CSS /*, processOptions */);