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

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 h1 + p,article h2 + p,article 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	Webpack	Create React App	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 h1 + p,article h2 + p,article h3 + p {
	margin-top: 0;
}

article :--heading + p {
	margin-top: 0;
}

importFrom

The importFrom option specifies sources where custom selectors can be imported from, which might be CSS, JS, and JSON files, functions, and directly passed objects.

postcssCustomSelectors({
	importFrom: 'path/to/file.css' // => @custom-selector :--heading h1, h2, h3;
});

article :--heading + p {
	margin-top: 0;
}

/* becomes */

article h1 + p, article h2 + p, article h3 + p {}

Multiple sources can be passed into this option, and they will be parsed in the order they are received. JavaScript files, JSON files, functions, and objects will need to namespace custom selectors using the customProperties or custom-properties key.

postcssCustomSelectors({
	importFrom: [
		'path/to/file.css',
		'and/then/this.js',
		'and/then/that.json',
		{
			customSelectors: { ':--heading': 'h1, h2, h3' }
		},
		() => {
			const customProperties = { ':--heading': 'h1, h2, h3' };

			return { customProperties };
		}
	]
});

exportTo

The exportTo option specifies destinations where custom selectors can be exported to, which might be CSS, JS, and JSON files, functions, and directly passed objects.

postcssCustomSelectors({
	exportTo: 'path/to/file.css' // @custom-selector :--heading h1, h2, h3;
});

Multiple destinations can be passed into this option, and they will be parsed in the order they are received. JavaScript files, JSON files, and objects will need to namespace custom selectors using the customProperties or custom-properties key.

const cachedObject = { customSelectors: {} };

postcssCustomSelectors({
	exportTo: [
		'path/to/file.css',   // @custom-selector :--heading h1, h2, h3;
		'and/then/this.js',   // module.exports = { customSelectors: { ':--heading': 'h1, h2, h3' } }
		'and/then/this.mjs',  // export const customSelectors = { ':--heading': 'h1, h2, h3' } }
		'and/then/that.json', // { "custom-selectors": { ":--heading": "h1, h2, h3" } }
		cachedObject,
		customProperties => {
			customProperties    // { ':--heading': 'h1, h2, h3' }
		}
	]
});