A rule for stylelint to disallow unused selectors

Usage no npm install needed!

<script type="module">
  import stylelintNoUnusedSelectors from '';



CircleCI Dependabot MIT License npm


stylelint-no-unused-selectors is a stylelint rule to disallow unused CSS selectors.

It works best with component-oriented applications where views are built on top of a lot of small components, each of which contains a template file (e.g., jsx or tsx) and its corresponding scoped CSS file (e.g., CSS Modules or PostCSS with BEM).

Assuming your component consists of following files:

├── index.js
├── FooComponent.jsx
└── FooComponent.css

when stylelint-no-unused-selectors runs on FooComponent.css, it extracts classes and ids from FooComponent.jsx and detects unused CSS rules.


If you'd like to jump into code, you can find our examples in the repository that are close to real-world situations.

With the built-in plugins, it supports

See the documentations of built-in plugins for more details.


yarn add stylelint stylelint-no-unused-selectors


It works as a stylelint rule, and its plugin name is plugin/no-unused-selectors. An example configuration of stylelint would look like:

  "plugins": [
  "rules": {
    "plugin/no-unused-selectors": true

See stylelint's documentation for more details.


By passing a configuration object described below as the rule's setting value, you can customise the rule's behaviours.

The default configuration is:

  "rules": {
    "plugin/no-unused-selectors": {
      "resolve": {
        "documents": [
      "plugins": [
          "test": "\\.html?quot;,
          "plugin": "stylelint-no-unused-selectors-plugin-html"
          "test": "\\.jsx?quot;,
          "plugin": "stylelint-no-unused-selectors-plugin-jsx",
          "options": {
            "sourceType": "module",
            "plugins": ["jsx", "flow"]
          "test": "\\.tsxquot;,
          "plugin": "stylelint-no-unused-selectors-plugin-tsx"


Type: Array<string>

This field tells the rule how to find a template file from a CSS file. The paths are evaluated from the top to the bottom and the first path that exists will be used.

Available variables are as follows:

Name Description Example (/project_root/components/Foo/Bar.css)
{cssDir} The path to a directory that contains a CSS file /project_root/components/Foo
{cssDirName} The name of a directory that contains a CSS file Foo
{cssName} The file name of a CSS file without its extension Bar


Type: Array<Plugin>

stylelint-no-unused-selectors relies on plugins to extract classNames/ids and/or determine if a selector is used in a template file.


Type: string (the value will be directly compiled with new RegExp())

Plugin.test represents what kind of template files should be processed with a plugin.


Type: string

A name of a plugin that is applied to template files, which is identical to its package name.


Type: any (optional)

An optional object that will be passed to a plugin, which can be used as parser's configurations or to change the plugin's behaviour. See each plugin's document to know what kind of options are available.


Built-in Plugins

Writing a new plugin

(To be written)


The MIT License.

Existing Tools

Please note that all the following tools are to remove unused rules, not to lint CSS files.

  • UnCSS uses a similar postcss and jsdom approach, but it can only run on pure HTML code.
  • DropCSS has its own HTML and CSS parsers, which contributes to fast and thorough cleanup outputs. It can only run on pure HTML code though.
  • PurifyCSS accepts various types of document including HTML, JS and PHP. It has an unique feature that simplifies JS via UglifyJS to extract classNames even if they are constructed dynamically. It detects classNames based on regular expressions, which unfortunately might account for its relatively high false negative rate.
  • PurgeCSS is a highly customisable tool thanks to its flexible plugin system. It can run on any kinds of contents as long as there is a plugin.