postcss-custom-selectors

What is postcss-custom-selectors?

The postcss-custom-selectors npm package is a plugin for PostCSS, a tool for transforming CSS with JavaScript. This package allows developers to define custom selectors in their CSS, which can be reused throughout the stylesheet. This helps in writing more maintainable and readable CSS by reducing repetition and promoting clearer structure.

What are postcss-custom-selectors's main functionalities?

Defining Custom Selectors

This feature allows you to define a custom selector, :--heading, which targets h1, h2, and h3 tags. Any style rules applied to :--heading will be applied to these elements, making it easier to manage styles for all headings in one place.

@custom-selector :--heading h1, h2, h3; 

:--heading { 
  font-weight: bold; 
}

Reusing Custom Selectors in Media Queries

Custom selectors can also be reused within media queries. This example shows a custom selector :--button used within a media query to apply specific styles to all elements with the class .btn on screens wider than 768 pixels.

@custom-selector :--button .btn; 

@media (min-width: 768px) { 
  :--button { 
    padding: 10px 15px; 
  } 
}

Other packages similar to postcss-custom-selectors

postcss-extend-rule

This package allows you to use a placeholder selector that can be extended within rulesets, similar to how Sass functions. It differs from postcss-custom-selectors by focusing on extending existing selectors rather than defining reusable custom selectors.

postcss-mixins

PostCSS Mixins supports defining reusable chunks of code, which can be included in other rulesets. It is similar to postcss-custom-selectors in promoting DRY (Don't Repeat Yourself) principles but uses mixins instead of custom selectors for reusability.

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 */);

PostCSS Custom Selectors runs in all Node environments, with special instructions for:

• Node
• PostCSS CLI
• PostCSS Load Config
• Webpack
• Next.js
• Gulp
• Grunt

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 */);