Troubleshoot Remove Unused CSS display issues

This article is intended to teach you how to identify and fix layout issues caused by the Remove Unused CSS feature.

Heads up! This is an advanced-level document dedicated to experienced users, developers and, overall, people comfortable around CSS and browser's Developer Tools.

If you need further assistance or simply prefer, you can contact WP Rocket's support instead.

First steps

It's important to make sure Remove Unused CSS is the cause of the problem with your site's layout. To confirm that, each of the following should be true:

The problem happens whenRemove Unused CSS is the only feature enabled (test with all other WP Rocket options disabled).
The problem does not happen whenRemove Unused CSS is disabled.
The problem persists after you've already regenerated the Used CSS.

Mobile-only Issues

If your layout issue is related only to the mobile version of your page, you should also try WP Rocket's Separate cache for mobile devices option in the Cache tab before doing anything else.

Safelisting CSS

Most Remove Unused CSS layout issues are caused by some of the needed styles being accidentally left out of the Used CSS during the CSS optimization process.

The Remove Unused CSS option in your WP Rocket plugin settings page includes a CSS Safelist text box that can be used to ensure the missing styles are included in the Used CSS by adding any of the following associated with the missing styles:

CSS Classes
CSS ID's
CSS Files
Font Families

For example, if the following CSS was missing from a page after the Remove Unused CSS optimization:

.my-class .other-class { background-color: green; }

Any of the following would safelist that style to make sure it is included in the Used CSS (universal selectors - (.*) - can be used to select any text):

.my-class .other-class
.my-class(.*)
(.*).other-(.*)

Safelisting font families is slightly different. If you notice one of your web fonts is not being applied, you can safelist it by using @font-name:

@Poppins

Safelisting CSS: Steps to resolve issues

While safelisting will usually fix your issue, sometimes it will not, so it's good to start by confirming whether or not safelisting will work in your case.

Begin by adding (.*) in the safelist box to safelist every possible style and save settings. Then wait until the Used CSS regenerates to see if the issue is solved.
If the issue is not fixed, it means safelisting won't work. In this case, you can try the alternative options in the sections below the safelisting steps, or contact WP Rocket support for further assistance.
If you confirm that safelisting will work, remove the (.*) from the safelist and proceed with the following steps to use your browser's Developer Tools to find the CSS that needs safelisted.

Using an incognito browser window, view the affected page with ?nowprocket added (https://yourdomain.com/?nowprocket). This will bypass WP Rocket's effects to see the non-cached version of the page with the CSS applied normally.
Open another incognito and load the normal https://yourdomain.com/ page with WP Rocket and Remove Unused CSS applied.
Right-click on the related element to open the contextual menu, and then click on "Inspect" to show the element's HTML and CSS markup (do this for both open windows so you can compare each side-by-side).

Please see the recording below for reference:
The goal is to look for any difference in the CSS classes, selectors, values, etc. between each. Most likely, you will find CSS applied to the ?nowprocket page that is missing on the page with Remove Unused CSS applied.
Tip: The affected CSS classes are not always found in the specific element tag. In some cases:
• There might be several affected CSS classes.
• The classes can also be located in higher-level elements of the DOM.
Once you've found the missing styles, the final step is to add the related CSS selectors to the safelist box, like this:

Heads up! Safelisting is not instantaneous.

If you visit the page immediately after adding a safelist item and saving changes, the Used CSS will take some time to regenerate, so even if you've not found the right solution, the issue will appear to be fixed until the new Used CSS is applied to the page ( Additional info).

Make sure the Used CSS generation is completed and applied by looking for the wpr-usedcss CSS block in your site's source code. Once that's confirmed, check if the issue has been fixed.

Alternatives to safelisting CSS

Preserve all CSS from specific sources

In some cases you may need to preserve entire inline styles and/or external stylesheets on the page. Here are some common cases:

When CSS contains dynamic selectors where numeric or alphanumeric value of classes and IDs is changing on each page load.
When JavaScript relies on the presence of the stylesheet or inline style on the page.

The following guides are available for these scenarios:

For stylesheets: Prevent CSS files from being removed by Remove Unused CSS.
For inline CSS: Prevent inline styles from being removed by Remove Unused CSS.

When these are used, the CSS from the associated external and/or inline styles will still also be included within the Used CSS.

Remove all CSS from from specific sources

Since WP Rocket 3.14.1, the rocket_rucss_skip_styles_with_attr filter can be used to target the HTML attributes applied to <style> and <link> elements. which does all of the following while the Remove Unused CSS optimization is applied:

If a CSS file is targeted, it removes that file from the page and its contents are not included in the Used CSS.
If an inline <style> tag is targeted, it removes those styles from the page and its contents are not added to the Used CSS.

This can be useful in cases where certain styles should be applied only under specific conditions. For example, keeping some styles under certain conditions might result in a broken layout on a page.

Example

With the following snippet, any inline CSS or stylesheet with the skip_me or skip_me_too attributes won't be added to the Used CSS:

add_filter( 'rocket_rucss_skip_styles_with_attr', function( $skipped_attributes ){
		$skipped_attributes = ['skip_me', 'skip_me_too'];
		return $skipped_attributes;
	});

In this case, the CSS rules in the following inline style won't be included in the Used CSS and will also be removed from their original location in the HTML source of the page:

<style skip_me="1" id="testid">
	div{display:none;}
</style>

And also, the following file will be removed from the page and its CSS rules will not be included in the Used CSS:

<link href="example.com/rocket-test-data/styles/rucss_styles7.css" rel="stylesheet" skip_me_too="1">

In case you're not sure how, you can use our guide about adding code snippets for your site.

Preserve CSS in its original source while excluding it from Used CSS

You can combine the effects of the previous two sections. If you use them both to target a common CSS file or inline block of CSS, the result is that it will remain applied to pages as it normally is, while also excluding its styles from the Used CSS.

Randomly broken CSS

This specific type of issue happens only sometimes, almost in a random basis, and the layout of the page is severely damaged because most styles are missing.

The issue is likely due to our Used CSS generation tool encountering a firewall or bot challenge page on your site. This causes incorrect Used CSS to be generated, and later applied.

Clearing Used CSS on affected URLs may provide a temporary fix, but long-term solutions include:

Rate-limiting: Check if your site is using any form of bot rate limiting rules, and allowlist our IPs there too. These rules might be set at the server level, or via WordPress plugin. For example, if you are using Wordfence, their Rate Limiting feature can interfere in the used CSS generation
Allow IPs: Ensure the IPs found in this list are allow-listed by your server, firewall, or security plugin.
Use a helper plugin to discard "failed" attempts:

WP Rocket | RUCSS Set Minimum Acceptable Size

This plugin will set the minimum size for the used CSS to be considered valid in 10KB. Anything less than that will be discarded to avoid breaking your pages.

If the problem continues, please copy the HTML of the broken page to a text file and send it to our team with your support ticket.

Incompatible third party features

Please disable any third party (plugin or theme) CSS optimizations, as they can often conflict with WP Rocket's Remove Unused CSS functioning. Clear Used CSS after disabling and check if your problem is resolved.

The following is a list of third party features known to conflict (though it's not an exhaustive list), so please make sure you're not using any of these:

Incompatible CSS

If your site's base CSS is invalid (i.e. it contains parse or value errors detected on this official CSS validator), it may cause issues with WP Rocket's CSS parser. If your CSS cannot be parsed correctly, it could cause incorrect CSS to be included in the Used CSS, which could also cause a broken layout, or a non-generated Used CSS.

Our tool can handle some syntax errors, but if you're having issues it is recommended to check for CSS parse errors using the testing tool suggested above. Correct them if needed, then regenerate the Used CSS and check if the problem is fixed.

Please note! You're invited to contact WP Rocket's support if:

You get stuck at any step of this process.
The safelist is not working, i.e., the affected CSS are still removed.
You're interested on reporting your findings, as it's also in our interest to have record of all affected CSS.

Automatic Compatibility

We maintain and apply automatic compatibility for each new layout issue we discover so the same issues won't continue to happen to others using the same themes and plugins.

Note: Any combination of CSS/JavaScript by other plugins/themes needs to be disabled because the safelisting process uses the original CSS and JavaScript files as conditions to set the automatic safelist.