Generating Critical CSS

  5 min read 

Critical CSS is the small slice of styles needed to render the top of a page. xSpeed Cache Pro can store that CSS per URL, inline it in the <head>, and push the rest of your stylesheets out of the way so the page starts painting sooner.

What this does

When you enable Critical CSS, xSpeed Cache Pro does two things on each front-end page that has stored critical CSS:

It inlines the cached critical CSS directly in the <head> of the page.
It defers the remaining stylesheets so they no longer block the first paint.

The critical CSS is stored per URL, so /about and /contact can each have their own.

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

Why use it

Browsers normally wait for every linked stylesheet to download before they paint a page. By inlining only the above-the-fold styles and deferring the rest, the visitor sees content sooner. This usually improves how fast the page feels, and it can help your First Contentful Paint and Largest Contentful Paint scores.

Requirements

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

How to enable it

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

How to add critical CSS

There are two ways to get critical CSS into xSpeed Cache Pro.

Connect a generator endpoint (optional). If you have a service that produces critical CSS, set the Generator endpoint URL and, if it needs one, the Generator API key. The dashboard then has a Generate action that sends the page URL to your service and stores the CSS it returns. Your endpoint should accept a POST with the URL and return JSON in the shape { "css": "..." }.

Upload it manually. You can push CSS in directly through the REST API or WP-CLI. This is handy if you already have critical CSS from another tool. Both the URL and the CSS are required.

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

Settings explained

Setting	What it does	Default
Enable Critical CSS	Inlines cached critical CSS in the `<head>` and defers the rest of the stylesheets	Off
Generator endpoint URL	Optional service that returns critical CSS for a URL	Empty
Generator API key	Sent as a Bearer token to the endpoint above	Empty
Defer remaining stylesheets	Loads non-critical stylesheets without blocking the first paint	On

Enable Critical CSS. The master switch. When it is off, nothing changes on the front end. When it is on and critical CSS is stored for the current URL, that CSS is inlined.

Generator endpoint URL. The address of your critical CSS service. xSpeed Cache Pro POSTs the page URL to it and expects { "css": "..." } back. Leave it empty if you only add 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.

Defer remaining stylesheets. When on, each non-critical <link rel="stylesheet"> is switched to load without blocking paint, with a <noscript> fallback for visitors who have JavaScript turned off. Turn this off if you only want the inline critical CSS without changing how the other stylesheets load.

Opting a stylesheet out of deferral

Some stylesheets need to keep blocking the paint (certain font styles, for example). To leave one alone, add the attribute data-xspeed-keep to its <link> tag. xSpeed Cache Pro will skip any stylesheet that carries it.

How storage and invalidation work

Critical 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 200 KB. Most critical CSS is far smaller than this.
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

Generate or add critical CSS for your most visited templates first: the home page, a typical post, and a typical page.
Re-generate critical CSS after a design change. Saving a post clears its entry, but a theme-wide CSS change may need a manual refresh.
Keep Defer remaining stylesheets on unless you have a specific reason to turn it off.
Test a few pages after enabling it. Look for any styling that flashes in late or shifts, and add data-xspeed-keep to stylesheets that must stay blocking.

Troubleshooting

The page looks unstyled for a moment. This usually means the critical CSS for that URL is missing or incomplete. Add or regenerate critical CSS for that page.

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.

A stylesheet I need keeps getting deferred. Add data-xspeed-keep to that stylesheet’s <link> tag so it is left blocking.

FAQ

Does xSpeed Cache Pro generate critical CSS on its own? No. You add the CSS manually or connect your own generator endpoint.

Can I use Critical CSS and Unused CSS together? 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.

Removing Unused CSS
Minify and Combine CSS
Clearing the Cache

Back to documentation Need more help? Contact support →