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 plugin to transform W3C CSS Extensions(Custom Selectors) to more compatible CSS.

简体中文

Installation

$ npm install postcss-custom-selectors

Quick Start

// dependencies
var fs = require('fs')
var postcss = require('postcss')
var selector = require('postcss-custom-selectors')

// css to be processed
var css = fs.readFileSync('input.css', 'utf8')

// process css using postcss-custom-selectors
var output = postcss()
  .use(selector())
  .process(css)
  .css

console.log('\n====>Output CSS:\n', output)  

Or just:

var output = postcss(selector())
  .process(css)
  .css

input:

@custom-selector :--heading h1, h2, h3, h4, h5, h6;

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

You will get:

article h1 + p,
article h2 + p,
article h3 + p,
article h4 + p,
article h5 + p,
article h6 + p {
  margin-top: 0;
}

CSS syntax

@custom-selector = @custom-selector :<extension-name> <selector>;

How to use

The custom selector is a pseudo-class, so you must use :-- to define it.

For example to simulate :any-link selector:

@custom-selector :--any-link :link, :visited;

a:--any-link {
  color: blue;
}

output:

a:link,
a:visited {
  color: blue;
}

You can even make some smart use like this:

@custom-selector :--button button, .button;
@custom-selector :--enter :hover, :focus;

:--button:--enter {

}

output

button:hover,
.button:hover,
button:focus,
.button:focus {

}

Options

lineBreak

(default: true)

Set whether multiple selector wrap.The default is turning on to be a newline.

Close the line breaks.

var options = {
  lineBreak: false
}

var output = postcss(selector(options))
  .process(css)
  .css

With the first example, the output will be:

article h1 + p, article h2 + p, article h3 + p, article h4 + p, article h5 + p, article h6 + p {
  margin-top: 0;
}

extensions

(default: {})

This option allows you to customize an object to set the <extension-name> (selector alias) and <selector>, these definitions will cover the same alias of @custom-selector in CSS.

var options = {
  extensions: {
    ':--any' : 'section, article, aside, nav'
  }
}

var output = postcss(selector(options))
  .process(css)
  .css;

input.css

@custom-selector :--any .foo, .bar; /* No effect */
:--any h1 {
  margin-top: 16px;
}

output:

/* No effect */
section h1,
article h1,
aside h1,
nav h1 {
  margin-top: 16px;
}

transformMatches

(default: true)

Allows you to limit transformation to :matches() usage If set to false:

input

@custom-selector :--foo .bar, .baz;
.foo:--foo {
  margin-top: 16px;
}

output

.foo:matches(.bar, .baz) {
  margin-top: 16px;
}

Usage

Node Watch

Dependence chokidar module.

var fs = require('fs')
var chokidar = require('chokidar')
var postcss = require('postcss')
var selector = require('postcss-custom-selectors')

var src = 'input.css'

console.info('Watching…\nModify the input.css and save.')

chokidar.watch(src, {
  ignored: /[\/\\]\./,
  persistent: true
}).on('all',
  function(event, path, stats) {
    var css = fs.readFileSync(src, 'utf8')
    var output = postcss(selector())
      .process(css)
      .css
    fs.writeFileSync('output.css', output)
  })

Grunt

module.exports = function(grunt) {
  grunt.initConfig({
    pkg: grunt.file.readJSON('package.json'),
    postcss: {
      options: {
        processors: [
          require('autoprefixer-core')({ browsers: ['> 0%'] }).postcss, //Other plugin
          require('postcss-custom-selectors')(),
        ]
      },
      dist: {
        src: ['src/*.css'],
        dest: 'build/grunt.css'
      }
    }
  });

  grunt.loadNpmTasks('grunt-contrib-uglify');
  grunt.loadNpmTasks('grunt-postcss');

  grunt.registerTask('default', ['postcss']);
}

Gulp

var gulp = require('gulp');
var rename = require('gulp-rename');
var postcss = require('gulp-postcss');
var selector = require('postcss-custom-selectors')
var autoprefixer = require('autoprefixer-core')

gulp.task('default', function () {
    var processors = [
        autoprefixer({ browsers: ['> 0%'] }), //Other plugin
        selector()
    ];
    gulp.src('src/*.css')
        .pipe(postcss(processors))
        .pipe(rename('gulp.css'))
        .pipe(gulp.dest('build'))
});
gulp.watch('src/*.css', ['default']);

Contributing

• Install the relevant dependent module.
• Respect coding style（Install EditorConfig）.
• Add test cases in the test directory.
• Run test.

$ git clone https://github.com/postcss/postcss-custom-selectors.git

$ git checkout -b patch

$ npm install

$ npm test

Changelog

License