View on GitHub


Remove unused styles from CSS

Download this project as a .zip file Download this project as a tar.gz file


Linux Build Status Windows Build status Coverage Status Dependency Status devDependency Status

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


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

  1. The HTML files are loaded by PhantomJS and JavaScript is executed.
  2. Used stylesheets are extracted from the resulting HTML.
  3. The stylesheets are concatenated and the rules are parsed by css-parse.
  4. document.querySelector filters out selectors that are not found in the HTML files.
  5. The remaining rules are converted back to CSS.


npm install -g uncss


Within Node.js:

var uncss = require('uncss');

var files   = ['my', 'array', 'of', 'HTML', 'files', 'or', ''],
    options = {
        ignore       : ['#added_at_runtime', /test\-[0-9]+/],
        media        : ['(min-width: 700px) handheld and (orientation: landscape)'],
        csspath      : '../public/css/',
        raw          : 'h1 { color: green }',
        stylesheets  : ['lib/bootstrap/dist/css/bootstrap.css', 'src/public/css/main.css'],
        ignoreSheets : [/fonts.googleapis/],
        timeout      : 1000,
        htmlroot     : 'public',
        report       : false

uncss(files, options, function (error, output) {

/* Look Ma, no options! */
uncss(files, function (error, output) {

/* Specifying raw HTML */
var rawHtml = '...';
uncss(rawHtml, options, function (error, output) {

At build-time

UnCSS can also be used in conjunction with other javascript build systems, such as Grunt or Gulp! Thanks to @addyosmani for creating:

and to @ben-eb for creating:

From the command line:

Usage: uncss [options] <file or URL, ...>
       e.g. uncss > stylesheet.css


  -h, --help                            output usage information
  -V, --version                         output the version number
  -i, --ignore <selector, ...>          Do not remove given selectors
  -m, --media <media_query, ...>        Process additional media queries
  -C, --csspath <path>                  Relative path where the CSS files are located
  -s, --stylesheets <file, ...>         Specify additional stylesheets to process
  -S, --ignoreSheets <selector, ...>    Do not include specified stylesheets
  -r, --raw <string>                    Pass in a raw string of CSS
  -t, --timeout <milliseconds>          Wait for JS evaluation
  -H, --htmlroot <folder>               Absolute paths' root location

Note that you can pass both local file paths and URLs to the program.

/* uncss:ignore */
.selector1 {
    /* this rule will be ignored */

.selector2 {
    /* this will NOT be ignored */


Copyright (c) 2013 Giacomo Martino. See the LICENSE file for license rights and limitations (MIT).