3 [![NPM version](https://img.shields.io/npm/v/uncss.svg)](https://www.npmjs.com/package/uncss)
4 [![Linux Build Status](https://img.shields.io/travis/giakki/uncss/master.svg?label=Linux%20build)](https://travis-ci.org/giakki/uncss)
5 [![Windows Build status](https://img.shields.io/appveyor/ci/giakki/uncss/master.svg?label=Windows%20build)](https://ci.appveyor.com/project/giakki/uncss/branch/master)
6 [![Coverage Status](https://img.shields.io/coveralls/giakki/uncss.svg)](https://coveralls.io/r/giakki/uncss?branch=master)
7 [![Dependency Status](https://img.shields.io/david/giakki/uncss.svg)](https://david-dm.org/giakki/uncss)
8 [![devDependency Status](https://img.shields.io/david/dev/giakki/uncss.svg)](https://david-dm.org/giakki/uncss#info=devDependencies)
10 UnCSS is a tool that removes unused CSS from your stylesheets.
11 It works across multiple files and supports Javascript-injected CSS.
14 The process by which UnCSS removes the unused rules is as follows:
16 1. The HTML files are loaded by [PhantomJS](https://github.com/Obvious/phantomjs) and JavaScript is executed.
17 2. All the stylesheets are parsed by [PostCSS](https://github.com/postcss/postcss).
18 3. `document.querySelector` filters out selectors that are not found in the HTML files.
19 4. The remaining rules are converted back to CSS.
32 var uncss = require('uncss');
34 var files = ['my', 'array', 'of', 'HTML', 'files', 'or', 'http://urls.com'],
36 ignore : ['#added_at_runtime', /test\-[0-9]+/],
37 media : ['(min-width: 700px) handheld and (orientation: landscape)'],
38 csspath : '../public/css/',
39 raw : 'h1 { color: green }',
40 stylesheets : ['lib/bootstrap/dist/css/bootstrap.css', 'src/public/css/main.css'],
41 ignoreSheets : [/fonts.googleapis/],
48 uncss(files, options, function (error, output) {
52 /* Look Ma, no options! */
53 uncss(files, function (error, output) {
57 /* Specifying raw HTML */
60 uncss(rawHtml, options, function (error, output) {
66 UnCSS can also be used in conjunction with other javascript build systems, such as [Grunt](https://github.com/gruntjs/grunt), [Broccoli](https://github.com/broccolijs/broccoli#readme) or [Gulp](https://github.com/gulpjs/gulp)!
68 - [grunt-uncss](https://github.com/addyosmani/grunt-uncss) – Thanks to [@addyosmani](https://github.com/addyosmani)
69 - [gulp-uncss](https://github.com/ben-eb/gulp-uncss) – Thanks to [@ben-eb](https://github.com/ben-eb)
70 - [broccoli-uncss](https://github.com/sindresorhus/broccoli-uncss) - Thanks to [@sindresorhus](https://github.com/sindresorhus)
72 ### From the command line:
75 Usage: uncss [options] <file or URL, ...>
76 e.g. uncss http://getbootstrap.com/examples/jumbotron/ > stylesheet.css
80 -h, --help output usage information
81 -V, --version output the version number
82 -i, --ignore <selector, ...> Do not remove given selectors
83 -m, --media <media_query, ...> Process additional media queries
84 -C, --csspath <path> Relative path where the CSS files are located
85 -s, --stylesheets <file, ...> Specify additional stylesheets to process
86 -S, --ignoreSheets <selector, ...> Do not include specified stylesheets
87 -r, --raw <string> Pass in a raw string of CSS
88 -t, --timeout <milliseconds> Wait for JS evaluation
89 -H, --htmlroot <folder> Absolute paths' root location
90 -u, --uncssrc <file> Load these options from <file>
93 **Note that you can pass both local file paths (which are processed by [glob](https://github.com/isaacs/node-glob)) and URLs to the program.**
95 - **ignore** (Array): provide a list of selectors that should not be removed by UnCSS. For example, styles added by user interaction with the page (hover, click), since those are not detectable by UnCSS yet. Both literal names and regex patterns are recognized. Otherwise, you can add a comment before specific selectors:
100 /* this rule will be ignored */
104 /* this will NOT be ignored */
108 - **media** (Array): By default UnCSS processes only stylesheets with media query "_all_", "_screen_", and those without one. Specify here which others to include.
110 - **csspath** (String): Path where the CSS files are related to the HTML files. By default, UnCSS uses the path specified in the `<link rel="stylesheet" href="path/to/file.css"/>`.
112 - **stylesheets** (Array): Use these stylesheets instead of those extracted from the HTML files.
114 - **ignoreSheets** (Array): Do not process these stylesheets, e.g. Google fonts. Accepts strings or regex patterns.
116 - **raw** (String): Give the task a raw string of CSS in addition to the existing stylesheet options; useful in scripting when your CSS hasn't yet been written to disk.
118 - **timeout** (Number): Specify how long to wait for the JS to be loaded.
120 - **htmlroot** (String): Where the project root is. Useful for example if you are running UnCSS on _local_ files that have absolute href to the stylesheets, i.e. `href="/css/style.css"`.
122 - **report** (Boolean): Return the report object in callback.
124 - **uncssrc** (String): Load all options from a JSON file. Regular expressions for the `ignore` and `ignoreSheets` options should be wrapped in quotation marks.
126 Example uncssrc file:
140 ### As a PostCSS Plugin
142 UnCSS can be used as a [PostCSS](https://github.com/postcss/postcss) Plugin.
145 postcss([ require('postcss-uncss').postcssPlugin ]);
148 See [PostCSS docs](https://github.com/postcss/postcss) for examples for your environment.
150 **Note:** Depending on your environment, you might not be able to use giakki/uncss as a PostCSS plugin since the plugin is not directly exported. In such cases, use the wrapper library [postcss-uncss](https://github.com/RyanZim/postcss-uncss).
154 - **html** (Array): provide a list of html files to parse for selectors and elements. Usage of [globs](https://github.com/isaacs/node-glob) is allowed.
156 - **ignore** (Array): provide a list of selectors that should not be removed by UnCSS. For example, styles added by user interaction with the page (hover, click), since those are not detectable by UnCSS yet. Both literal names and regex patterns are recognized. Otherwise, you can add a comment before specific selectors in your css:
161 /* this rule will be ignored */
165 /* this will NOT be ignored */
169 ##### Example Configuration
173 html: ['index.html', 'about.html', 'team/*.html'],
179 Copyright (c) 2013 Giacomo Martino. See the [LICENSE](/LICENSE.md) file for license rights and limitations (MIT).