Removing Unused CSS

  5 min read 

Most themes and plugins load far more CSS than any single page actually uses. xSpeed Cache Pro can store a slimmed-down stylesheet per URL, inline it, and strip the original stylesheets so the browser downloads less.

What this does

When you enable Unused CSS, xSpeed Cache Pro does this on each front-end page that has a stored pruned stylesheet:

It inlines the pruned stylesheet directly in the page.
It strips the original <link rel="stylesheet"> tags, since the bytes you removed are exactly the ones being pruned out.

The pruned CSS is stored per URL, so each page can have its own.

Note: xSpeed Cache Pro does not include a built-in unused-CSS generator. You supply the pruned CSS yourself, either by uploading it or by connecting your own generator service. See “How to add pruned CSS” below.

This is different from Critical CSS. Critical CSS is additive: it inlines the above-the-fold styles and defers the rest. Unused CSS is a replacement: it inlines a full pruned stylesheet and removes the originals.

Why use it

Unused CSS rules still cost download time and parse time, even when they never apply to the current page. Replacing the page’s stylesheets with a pruned version means the browser fetches and processes fewer styles, which can lower total page weight and improve render time.

Requirements

xSpeed Cache Pro must be installed and active. Unused CSS is a Pro feature.
To generate the pruned CSS automatically, you need a generator service that accepts a URL and returns the pruned CSS. This is optional. You can also upload it by hand.

How to enable it

Go to the xSpeed Cache settings and open the Unused CSS panel.
Turn on Enable Unused CSS.
Add pruned CSS for the URLs you care about (see below).
Save your changes.

Important: Stripping the original stylesheets only happens when a pruned stylesheet is actually stored for that URL. If nothing is stored, the page is left untouched. So enabling the toggle alone does not change a page until you add its CSS.

How to add pruned CSS

Connect a generator endpoint (optional). Set the Generator endpoint URL and, if needed, the Generator API key. The dashboard’s Generate action sends the page URL to your service. Your endpoint should accept a POST containing the URL (with a mode of unused-css) and return JSON in the shape { "css": "..." }.

Upload it manually. You can push CSS in directly through the REST API or WP-CLI. Both the URL and the CSS are required.

Tip: WP-CLI users can run wp xspeed ucss generate --url=<url> to call the configured endpoint, wp xspeed ucss list to see what’s stored, and wp xspeed ucss clear to remove entries.

Settings explained

Setting	What it does	Default
Enable Unused CSS	Inlines the pruned stylesheet and strips the original stylesheets when pruned CSS is stored for the URL	Off
Generator endpoint URL	Optional service that returns pruned CSS for a URL	Empty
Generator API key	Sent as a Bearer token to the endpoint above	Empty

Enable Unused CSS. The master switch. When on and a pruned stylesheet is stored for the current URL, the original stylesheet links are stripped and the pruned blob is inlined instead.

Generator endpoint URL. The address of your unused-CSS service. xSpeed Cache Pro POSTs the page URL to it and expects { "css": "..." } back. Leave it empty if you only upload CSS by hand.

Generator API key. If your endpoint needs authentication, the key is sent as a Bearer token. Leave it empty if your endpoint does not require one.

Opting a stylesheet out of stripping

Some stylesheets must stay (fonts, the admin bar, and similar). To keep one, add the attribute data-xspeed-keep to its <link> tag. xSpeed Cache Pro leaves any stylesheet carrying it in place.

How storage and invalidation work

Pruned CSS is stored per URL, with /foo and /foo/ treated as the same page.
Storage holds up to 200 URLs. When it is full, the oldest entries are removed first.
Each stored entry is capped at 500 KB, which is larger than the Critical CSS cap because a pruned full stylesheet is bigger than above-the-fold-only CSS.
Stored CSS is cleared automatically when you purge all caches, and the entry for a post is cleared when that post is saved.

Best practices

Start with your most visited templates: the home page, a typical post, and a typical page.
Because Unused CSS removes the original stylesheets, test each page carefully after adding its CSS. Look for missing styles, then either regenerate the pruned CSS or mark the needed stylesheet with data-xspeed-keep.
Re-generate pruned CSS after design or plugin changes that add new styles.

Troubleshooting

A page lost some styling. The pruned stylesheet for that URL is probably missing rules the page uses. Regenerate the pruned CSS for that page, or add data-xspeed-keep to the stylesheet that must stay.

The Generate action returns an error. Check that the Generator endpoint URL starts with http:// or https://, that the API key is correct, and that your service returns JSON with a css field. xSpeed Cache Pro reports the HTTP status or error message it received.

Nothing changed after I turned it on. Stripping only happens when pruned CSS is stored for the URL. Add the CSS for that page first.

FAQ

What is the difference between Unused CSS and Critical CSS? Critical CSS inlines above-the-fold styles and defers the rest. Unused CSS inlines a pruned full stylesheet and removes the originals entirely.

Can I run both at the same time? Both can be enabled. If both would inline into the same <head> for the same URL, xSpeed Cache Pro falls back to Critical CSS only to avoid a conflict.

Generating Critical CSS
Minify and Combine CSS
Clearing the Cache

Back to documentation Need more help? Contact support →