Fixing Unused CSS Without Breaking Your Site

Why unused CSS matters, and when it does not

Every byte of CSS in a stylesheet linked from the page head has to download and be parsed before the browser draws anything. Unused rules also add work when the browser matches selectors against elements. On a fast laptop that cost is small; on a mid-range phone on a patchy mobile connection it shows up as a longer blank screen.

Whether it is worth your time depends on three things:

The CSS Checker estimates how much of your CSS goes unused. Read that estimate together with file size and whether the file is render-blocking: a high percentage of a tiny file is not worth a day's work, while a moderate percentage of a very large blocking file might be. If you have not yet dealt with render-blocking, Fixing render-blocking CSS is often the better first job.

Where unused CSS comes from

Knowing the source tells you the safest fix. Most sites have a mix of these:

• Frameworks loaded whole. A full UI framework stylesheet brings grids, forms, modals, carousels and utilities for every possible layout, even if you use a handful.
• Icon and font libraries. An icon font stylesheet can contain a rule for every icon in the set, while the site uses a dozen.
• Old features nobody removed. Styles for a promotion that ended, a redesign that replaced a component, or a widget that was uninstalled.
• Plugin and app styles loaded everywhere. A contact form or slider plugin that adds its CSS to every page, not just the one with the form or slider.
• Theme options you never switched on. Commercial themes ship styles for every layout variant.
• Duplicate rules. The same component styled twice, once in an old file and once in a new one, where only the second copy matters.

The first two are best fixed by importing only the parts you use. The middle three are best fixed by deleting or conditionally loading. Duplicates are fixed by merging. Automated trimming tools help with all of them but are a safety net, not a replacement for understanding what is there.

Measuring unused CSS properly

The Coverage panel

In Chrome or Edge, open developer tools, open the command menu with Ctrl+Shift+P (or Cmd+Shift+P on a Mac), type "coverage" and choose Show Coverage. Click the reload button in the panel. You get a list of every CSS and JavaScript file with its total size and the bytes that went unused. Filter the list to CSS. Clicking a file opens it in the Sources panel with a coloured bar beside each rule: one colour for rules that matched, another for rules that did not.

That view is where most people stop, and it is where the mistakes start. Coverage records what matched while you were watching. If you did not open the mobile menu, the menu styles are "unused". If you did not submit a form with an error, the error styles are "unused". If you were logged out, the account area styles are "unused".

Recording a realistic session

Keep the Coverage panel recording while you work through a checklist on each key template:

1. Load the page at a phone width, then resize to tablet and desktop widths so each media query applies.
2. Open and close every menu, accordion, tab set, modal and cookie banner.
3. Hover and focus links, buttons and form fields, including keyboard focus.
4. Submit forms empty to trigger validation messages, and complete one to see the success state.
5. Switch colour scheme if you support dark mode, and turn on reduced motion if you have rules for it.
6. Repeat logged in, with items in a basket, or in any other state that changes the page.

Export the coverage result from the panel so you can compare it with later runs.

Automating the measurement

For larger sites, a headless browser can collect CSS coverage for a list of URLs and a script of interactions. Puppeteer and Playwright both expose CSS coverage in Chromium, so you can combine many pages into one list of selectors that were used somewhere. That combined list is far more trustworthy than a single page view.

// coverage.mjs: collect used CSS ranges across several pages (Puppeteer)
import puppeteer from 'puppeteer';

const urls = [
  'https://example.co.uk/',
  'https://example.co.uk/services/',
  'https://example.co.uk/contact/'
];
const browser = await puppeteer.launch();
const page = await browser.newPage();
const results = [];
for (const url of urls) {
  await page.coverage.startCSSCoverage();
  await page.goto(url, { waitUntil: 'networkidle0' });
  await page.click('.menu-toggle').catch(() => {});
  results.push(...await page.coverage.stopCSSCoverage());
}
await browser.close();
console.log(JSON.stringify(results.map(r => ({ url: r.url, ranges: r.ranges })), null, 2));

The fix, step by step

Setting up PurgeCSS safely

PurgeCSS reads your content files, extracts every string that looks like a class name, and removes rules whose selectors do not match any of them. It works as a PostCSS plugin, a command-line tool, or through plugins for common bundlers.

// postcss.config.mjs
import purgecss from '@fullhuman/postcss-purgecss';

export default {
  plugins: [
    purgecss({
      content: [
        './src/**/*.html',
        './src/**/*.{js,jsx,ts,tsx,vue}',
        './templates/**/*.twig'
      ],
      safelist: {
        standard: ['is-open', 'is-active', 'has-error', /^swiper-/],
        deep: [/^prose$/],
        greedy: [/tooltip/]
      },
      keyframes: true,
      fontFace: true
    })
  ]
};

The three safelist types behave differently. standard keeps selectors that match; deep also keeps everything nested inside a matching parent, which suits rich-text areas where editors can use any element; greedy keeps any selector that contains a match anywhere. The keyframes and fontFace options remove unused animations and font declarations as well as rules.

Protecting blocks in the stylesheet

For a section of CSS that must never be trimmed, such as styles for content pasted in by editors, wrap it in special comments:

/* purgecss start ignore */
.wysiwyg table { border-collapse: collapse; }
.wysiwyg blockquote { border-left: 4px solid #cbd5e1; }
/* purgecss end ignore */

The dynamic class problem

PurgeCSS and similar tools read your files as text. They cannot see a class name that only exists once code runs. This pattern will lose its styles:

// Class assembled at runtime: the tool never sees "alert-warning"
el.className = 'alert-' + level;

Either write the full names somewhere the tool can see them, for example in a lookup object such as { warning: 'alert-warning', error: 'alert-error' }, or add them to the safelist. The same applies to classes chosen in a CMS, returned from an API, or added by third-party scripts.

Platform and framework notes

Utility-first frameworks

Tailwind CSS generates only the classes it finds in your source files, so unused utilities are not the problem there. What goes wrong is detection: class names built from string fragments, content in folders the scanner does not look at, or files excluded by your ignore rules. Recent versions detect sources automatically and let you add paths with the @source directive; older versions use the content array in the config file. In both cases the fix for a missing style is to write the complete class name somewhere the scanner reads.

WordPress

Much WordPress unused CSS comes from plugins that load styles on every page. Performance plugins offer "remove unused CSS" features that generate trimmed CSS per page; they work, but test logged-in views, forms and WooCommerce pages carefully, and clear their cache after any design change. Loading plugin styles only where needed is often cleaner; see CSS in WordPress themes.

React and other component frameworks

Component-scoped CSS, such as CSS Modules, tends to be split along with the components that import it, so pages only load what their components need. Leftover global stylesheets and whole UI libraries are the usual source of unused CSS in these apps; the React and Next.js guide covers this.

Static sites with no build step

You can still run PurgeCSS once from the command line against your HTML files and stylesheet, review the output, and upload the trimmed file. Keep the original so you can compare and restore.

Mistakes that break sites

• Trusting one page view. Deleting everything Coverage marks red on the home page removes styles for every other template.
• Forgetting states. Menus, error messages, empty baskets, cookie banners and print styles are the usual casualties.
• Not scanning JavaScript. If your content globs cover only HTML, every class added by a script disappears.
• Trimming third-party widget CSS. Embedded booking, chat or review widgets often add their own markup after load; their styles look unused to static tools.
• Editing compiled output. Changes to a built file are overwritten by the next build. Fix the source.
• Treating it as done. New features add CSS. Recheck after each significant release.