Configuration Options

UnCSS is highly configurable to suit the needs of your project. Options can be passed programmatically, via the CLI, or through a configuration file.

Options Reference

Here is a comprehensive list of all available options.

Option	Type	Default	Description
banner	Boolean	true	Prepend a banner comment to the beginning of the generated CSS.
csspath	String	''	The path where CSS files are located relative to the HTML files. UnCSS first looks at the path in <link href="...">.
htmlroot	String	null	The root folder for resolving absolute paths in href attributes (e.g., /css/style.css).
ignore	Array	[]	An array of CSS selectors to ignore. These selectors will be kept in the final output, regardless of whether they are found in the HTML. Accepts strings and RegExp patterns.
ignoreSheets	Array	[]	An array of stylesheets to completely ignore. Accepts strings and RegExp patterns. Useful for external stylesheets like Google Fonts.
inject	String or Function	null	A path to a JavaScript file or a function to be executed in the jsdom context before UnCSS starts processing. Useful for simulating DOM changes.
jsdom	Object	{...}	An options object passed directly to the jsdom constructor. Allows for advanced configuration of the virtual DOM environment.
media	Array	[]	An array of media queries to process. By default, UnCSS only processes all, screen, and stylesheets with no media query.
raw	String	null	A raw string of CSS to be processed in addition to any stylesheets found or specified.
report	Boolean	false	If true, the programmatic API will return a report object detailing which selectors were used, unused, and the original CSS.
strictSSL	Boolean	true	Toggles SSL certificate verification when fetching remote HTML or CSS files.
stylesheets	Array	null	An array of stylesheet paths or URLs to process, overriding those found in the HTML files.
timeout	Number	0	The number of milliseconds to wait for JavaScript to execute before processing the page.
uncssrc	String	null	Path to a JSON configuration file. Options in this file will be loaded, and can be overridden by other options.
userAgent	String	'uncss'	The user-agent string to use when making HTTP requests.

Using a Configuration File (.uncssrc)

For larger projects, managing options via the command line can be cumbersome. UnCSS supports loading options from a JSON configuration file, typically named .uncssrc.

You can specify a custom path to this file using the --uncssrc CLI flag or the uncssrc option.

Example .uncssrc file

{
    "ignore": [
        ".unused-but-keep",
        "/^#js/"
    ],
    "stylesheets": [
        "/css/override.css"
    ],
    "timeout": 1000
}

Note on Regular Expressions: Since JSON does not support native regular expressions, you must store them as strings. UnCSS will automatically convert strings that begin and end with a forward slash (/) into RegExp objects for the ignore and ignoreSheets options.