Troubleshoot Remove Unused CSS 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 that your make sure Remove Unused CSS is causing the problem on your site's layout. For this purpose, the problem should happen when:

• Remove Unused CSS is the only feature enabled,
• all the other WP Rocket features across the Media and File Optimization tabs are disabled, and,
• you've already regenerated the Used CSS.

Incompatible third party features

The following third party features overlap Remove Unused CSS functioning and shouldn't be enabled at the same time:

• RapidLoad Power-Up for Autoptimize
• Perfmatters' Remove Unused CSS

Incompatible CSS

WP Rocket's Used CSS generation tool uses a CSS parser. If the base CSS is invalid, i.e. it contains parse or value errors detected on this official CSS validator, it may end up in incorrect CSS, 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 if your site's CSS is valid.

Exclude CSS from being added to the Used CSS

Since WP Rocket 3.14.1, you can use the  rocket_rucss_skip_styles_with_attr filter for exclude styles from being added to the Used CSS.

This is useful in cases where certain styles should be applied under specific conditions only, and keeping them in the resulting Used CSS will break the site.

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 added to the Used CSS:

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

And also the content of this file:

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

Here's how can add the above snippet: Add code snippets.

Safelist CSS 

In most cases, if a style is missing, it means you need to retain CSS and ensure it's added to the resulting Used CSS. 

The Remove Unused CSS feature includes the CSS safelist text box where you can safelist values. You can add CSS classes, id's, attributes, fonts families, and CSS files.

Note:The combination of CSS/JavaScript from 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.

You can find more information on the How to exclude files from this optimization / retain selected CSS rules on a page section of this article.

Technique to find the CSS to safelist

This technique consists of comparing the broken and working versions of the site, using browser's Developer Tools, in order to find the right CSS to safelist.

1. Make sure you've followed the first steps section of this article.
2. Using an incognito mode browser window, add ?nowprocket to the URL of the affected page, and hit Enter, e.g.: Visit https://yourdomain.com/?nowprocket.
   
   This will bypass WP Rocket's effects, you will see the non-cached version of the page, and the CSS will be as expected.
3. Identify the affected layout element.
4. Right-click on the element to open the contextual menu, and then click on "Inspect".
   
   See the below recording for reference:
   
   
   
5. This will open the Developer tools panel, and highlight the element's markup. Keep this tab/window open.
6. In another tab, visit the page with the CSS issue using its regular URL, e.g.: Visit https://yourdomain.com/.
7. Right-click→ Inspect the element or the area around the element.
8. This is where a process of comparison starts.
   
   Some OS let you drag the windows to the sides of the screen, to get a side-by-side comparison view, as shown below:
   
   

   

9. You'll need to thoroughly compare the related markup of the affected element, in both versions of the page, cached and non-cached.
   
   You're looking for any difference in the CSS classes, selectors, values.
   
   

   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.

10. Once you find the missing CSS class, you can add it to the CSS safelist box as explained here, and once the Used CSS is regenerated, you can test the results.
    
    

    Heads up! Safelisting is not instantaneous.
    
    If you visit the page immediately after saving changes, the Used CSS won't be applied, and you may get false positives.
    
    After adding a value to the safelist box, the Used CSS will need to be regenerated, and then applied. See more.
    
    Make sure the Used CSS generation is completed and applied by looking for the wpr-usedcss CSS block on your site's source code.

Alternatives to safelisting CSS

Example

A common problem is that, when applied, the resulting Used CSS doesn't include a specific CSS property resulting in an element using the wrong style.

In this example, the background color of an image is missing when Remove Unused CSS is enabled to the https://wp-rocket.me/ website.

As instructed in the above section, these steps were followed:

1. The first steps are completed.
2. Visit https://wp-rocket.me/?nowprocket.
3. The affected image is identified.
4. Right-click on the image, and click on "Inspect".
5. Developer Tools panel is opened.
6. Visit https://wp-rocket.me/.
7. Right-click→ Inspect on the affected image.
8. Comparison starts. Below you can find a reference side-by-side view:
   
9. The relevant HTML and CSS is compared in both windows.
   
   And the missing CSS is found to be the background-color: black property, as shown below:
   
   

   Therefore, the value to add the safelist box is the full line of CSS selectors applied to the element:
   

   .wp-block-media-text .wp-block-media-text__media img

10. Final steps are to add the selectors to the safelist box, like this:
    

    

    Remember, once a new value is added to the safelist box, the Used CSS will be removed from the page, and the issue will be fixed while the new Used CSS is regenerated.
    
    So, it's very important to wait until the new Used CSS is applied to the page again, and clear any additional cache layer, until you know if the problem is fixed or not.

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.