UnCSS – Slim Down Your CSS

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

Looking for big optimization gains on your site? There’s nothing better than removing stuff you don’t need! Whether it’s code, images or dependencies, getting rid of the stale code is like the first beer after a long stressful day. When it comes to CSS, there’s no better tool for optimazation than UnCSS. It’s a powerful NodeJS powered utility that removes unused CSS from your stylesheets.

Using Frontend Build or other CSS frameworks?

Frameworks like Frontend Build, Bootstrap, Foundation or even your own are great at speeding up development time and providing a starting point — problem is, unless you take time to eliminate the pieces you did not use, you’ll ship bloated code to your users. UnCSS comes to the rescue!

How does UnCSS do it’s magic?

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

Let’s get started optimizing with UnCSS!

UnCSS is a cinch to use. In this post I’ll go over how it’s used and configured in Frontend Build (check it out).


// Task: uncss
gulp.task('uncss', ['compass', 'htmlmin'], () => {
  return gulp.src(paths.dirs().css + '/**/*.css')
      html: [config.paths.srcHtml],
      ignore: []

Here we have the uncss Gulp task. Configuration is pretty simple. First, in the gulp source we tell it where to find our CSS files. In Frontend Build, we use paths from the compass-options module to get the CSS path from Compass config. You can update it so it only targets certain directories/files, but by default it targets all CSS files within that directory.

Next, we need to tell UnCSS what pages to check against for unused styles. We define those pages in the UnCSS html option. In Frontend Build, all HTML documents found in the source directory are used. This should be updated to match your site pages (ex. http://yoursite.com/, http://yoursite.com/about, http://yoursite.com/contact, etc.)

Note: One recommendation to avoid the problem of defining multiple page is to use a styleguide page as your URL, or other reference HTML which is known to contain a complete copy of all possible markup on your site.

The ignore option

UnCSS can potentially strip out styles that only appear after user interaction. Some examples are classes that are added to the DOM by JS. UnCSS is equipped with an ignore option which allows you to specify which selectors should not be removed. Both literal names and regex patterns are recognized.

Why aren’t you using UnCSS?

There’s no arguing that years of maintaining, adding, and removing from a site will add excess code to the codebase. That excess code comes at the cost of users who have load the extra code, so eliminating the dead code is important. Give UnCSS a try — it’s an easy to use, automated helper to keep your codebase as tight as possible!

Helpful Resources

Author: Ben Marshall

Red Bull Addict, Self-Proclaimed Grill Master, Entrepreneur, Workaholic, Front End Engineer, SEO/SM Strategist, Web Developer, Blogger

Leave a Reply

Your email address will not be published. Required fields are marked *