uncss /uncss

Remove unused styles from CSS

★ 9,387⑂ 401👁 133⑃ 197● 303▤ 18
JavaScriptMITCreated 2013-04-18
Download: 0.17.30.17.3 ↓0.17.32020-02-11
+0
Daily
9,387
stars
401
forks
133
watchers
197
prs
303
issues
18
releases

README

UnCSS





UnCSS is a tool that removes unused CSS from your stylesheets.
It works across multiple files and supports Javascript-injected CSS.

 How

The process by which UnCSS removes the unused rules is as follows:

1. The HTML files are loaded by jsdom and JavaScript is executed.
2. All the stylesheets are parsed by PostCSS.
3. document.querySelector filters out selectors that are not found in the HTML files.
4. The remaining rules are converted back to CSS.

Please note:

-   UnCSS cannot be run on non-HTML pages, such as templates or PHP files. If you need to run UnCSS against your templates, you should probably generate example HTML pages from your templates, and run uncss on those generated files; or run a live local dev server, and point uncss at that.
-   UnCSS only runs the Javascript that is run on page load. It does not (and cannot) handle Javascript that runs on user interactions like button clicks. You must use the ignore option to preserve classes that are added by Javascript on user interaction.

 Installation

shell
npm install -g uncss


 Usage

 Online Server

-   https://uncss-online.com/ - Unofficial server, very convenient for testing or one-off usage!

 Within Node.js

js
var uncss = require('uncss');

var files = ['my', 'array', 'of', 'HTML', 'files', 'or', 'http://urls.com'],
    options = {
        banner: false,
        csspath: '../public/css/',
        htmlroot: 'public',
        ignore: ['added_at_runtime', /test\-[0-9]+/],
        ignoreSheets: [/fonts.googleapis/],
        inject: function (window) {
            window.document.querySelector('html').classList.add('no-csscalc', 'csscalc');
        },
        jsdom: {
            userAgent: 'Mozilla/5.0 (iPhone; CPU iPhone OS 10_3 like Mac OS X)',
        },
        media: ['(min-width: 700px) handheld and (orientation: landscape)'],
        raw: 'h1 { color: green }',
        report: false,
        strictSSL: true,
        stylesheets: ['lib/bootstrap/dist/css/bootstrap.css', 'src/public/css/main.css'],
        timeout: 1000,
        uncssrc: '.uncssrc',
        userAgent: 'Mozilla/5.0 (iPhone; CPU iPhone OS 10_3 like Mac OS X)',
    };

uncss(files, options, function (error, output) {
    console.log(output);
});

/ Look Ma, no options! /
uncss(files, function (error, output) {
    console.log(output);
});

/ Specifying raw HTML /
var rawHtml = '...';

uncss(rawHtml, options, function (error, output) {
    console.log(output);
});


 At build-time

UnCSS can also be used in conjunction with other JavaScript build systems, such as Grunt, Broccoli or Gulp!

-   grunt-uncss – Thanks to @addyosmani
-   gulp-uncss – Thanks to @ben-eb
-   broccoli-uncss - Thanks to @sindresorhus

 From the command line

txt
Usage: uncss [options] 
    e.g. uncss https://getbootstrap.com/docs/3.3/examples/jumbotron/  stylesheet.css

Options:

  -h, --help                            output usage information
  -V, --version                         output the version number
  -i, --ignore   

Top issues

Latest release

0.17.3 0.17.3 2020-02-11

Snapshot: 2026-11-16T09:23:14Z · Data license Apache-2.0 · JSON