Usage Guide

This guide covers the primary ways to use PurifyCSS, from providing input files to configuring its behavior with options.

Providing Content and CSS

The purify function accepts two main arguments: content and css. Both can be provided as strings, file paths, or glob patterns.

Using Strings

For simple cases or dynamic content, you can pass strings directly.

const purify = require('purify-css');

const content = '<html><body><div class="my-class"></div></body></html>';
const css = '.my-class { color: red; } .other-class { color: blue; }';

const result = purify(content, css);
// result: .my-class { color: red; }

Using File Paths and Glob Patterns

For most projects, you'll want to point PurifyCSS to your source files. You can provide an array of file paths or glob patterns.

const purify = require('purify-css');

// An array of glob patterns for your content files
const content = ['**/*.html', 'src/js/**/*.js'];

// An array of glob patterns for your CSS files
const css = ['src/css/**/*.css'];

// The options object is optional
const options = {
  output: './dist/purified.css'
};

purify(content, css, options);

PurifyCSS will read all matching files, concatenate their contents, and then perform the purification process.

Configuration Options

You can customize PurifyCSS's behavior by passing an optional options object. Here are the available options:

  • output (String | Boolean): Filepath to write the purified CSS to. If false (default), the function returns the purified CSS as a string.
purify(content, css, { output: 'path/to/final.css' });
  • minify (Boolean): Set to true to minify the output CSS. Default: false.
purify(content, css, { minify: true });
  • info (Boolean): Set to true to log information about how much the CSS was reduced. Default: false.

purify(content, css, { info: true });
Output: 
    ________________________________________________
    |
    |   PurifyCSS has reduced the file size by ~ 33.8%
    |
    ________________________________________________

  • rejected (Boolean): Set to true to log the CSS rules that were removed. Default: false.
purify(content, css, { rejected: true });
  • whitelist (Array): An array of selectors that should not be removed, even if they aren't found in the content. This is useful for classes that are added dynamically at runtime in ways PurifyCSS can't detect.
  • Exact Match: ['my-class'] will keep any selector that is exactly my-class.
  • Wildcard Match: ['*modal*'] will keep any selector that contains the word modal (e.g., .modal-header, .modal-body).
const options = {
  whitelist: ['button-active', '*modal*']
};

purify(content, css, options);
  • cleanCssOptions (Object): An object of options to pass directly to the clean-css library when minify: true is used.

Using a Callback

PurifyCSS can be used with a callback function, which receives the purified CSS as its only argument. This is useful for asynchronous operations.

Callback Without Options

purify(content, css, function(purifiedResult) {
  console.log(purifiedResult);
});

Callback With Options

If you provide an options object, the callback should be the last argument.

const options = {
  minify: true
};

purify(content, css, options, function(purifiedAndMinifiedResult) {
  console.log(purifiedAndMinifiedResult);
});
Note: If the output option is specified, the callback will still be called, but the primary result will be written to the specified file.