LazyLoad for CSS background images

As of the 3.15 release, WP Rocket includes the LazyLoad for CSS background images feature, which is in charge of deferring the background images inserted via internal styles and CSS files. This helps the page to load faster because the background images will be loaded only when they need to be displayed.

You can enable this feature from the Media tab, in the LazyLoad section, as shown below:

enabling lazyload for CSS background images

Feature overview

The LazyLoad for CSS background images feature targets two types of background images:

Background images added via internal CSS.
Background images added from a CSS file.

This feature is fully automated, which means you don't need to specify which images or CSS selectors need to be included. Background images of your site will be lazyloaded right upon feature activation.

Using this feature will help you address the Defer offscreen images audit in Google Lighthouse-based tests, such as PageSpeed and GTmetrix.

The LazyLoad for CSS background images feature behavior is complementary to the LazyLoad for images feature, which also targets background images, but for those applied to these specific HTML tags via inline style attributes.

How to check if the feature is working

Behavior of background images at Developer Tools > Network

You can see the LazyLoad for CSS background images in action using the Network tab from Developer Tools, as shown below:

After enabling the LazyLoad for CSS background images feature, open the page with the background image in an incognito window.
Open the Developer Tools in your browser.
In Chrome: View > Developer > Developer Tools
Click the Network tab.
Click the Img filter
As you scroll down the page, the background image will be loaded.

Example

In the following GIF, you can see how the Stroke-Report-Brochure.webp image is loaded only after scrolling down the page:

lazyloaded image in the network

Changes in the markup

Additionally, a page with a background image(s) will have the following changes in its markup.

Changes in the HTML element

Once the image is successfully loaded, the HTML element will include the data-rocket-lazy-bg="loaded" attribute.

For example, the markup of a p element with a background image will change from:
```
<p class="some-class">
	
```
To:
```
<p class="some-class" data-rocket-lazy-bg="loaded">
	
```
Changes in the internal CSS

In the internal CSS block, the URL of the background image will be replaced by a CSS variable.

For example, the CSS style of the HTML element will change from:
```
p.some-class {
	background-image: url("https://yoursite.com/background-image.webp");
}
	
```
To:
```
p.some-class {
	background-image: var(--wpr-bg-aa111bb22-cc-33-ee-44ffgg55);
}
	
```
Changes in the CSS file

The CSS file containing the background image will have its content rewritten to include the CSS variable in the same way as shown above for images in internal CSS blocks.

Additionally, this new file will be renamed and stored in the cache folder.

From example, the CSS file will change from:
```
https://yourdomain.com/wp-content/css/css-file-with-background-image.css
	
```
To:
```
https://yourdomain.com/wp-content/cache/background-css/yourdomain.com/wp-content/css/css-file-with-background-image.css
	
```

How to exclude CSS background images from the LazyLoad

You can use the Excluded images or iframes box to exclude background images from this optimization.

In the box, you can add keywords, such as the image filename, CSS filename, CSS class or the domain from the image you need to exclude. If there are several entries, you should add them one per line, as shown below:

image exclusions Heads up! If you exclude a CSS file, all the images contained in it will be excluded from this feature.

You can confirm the exclusion worked by checking Developer Tools > Network, as the image will be loaded immediately on page load.

Note: the HTML element of an excluded image will still use the data-rocket-lazy-bg="loaded" attribute. However, the image will not be lazyloaded, it will be loaded instantly on page load.

It's only recommended to use the exclusion box when:

The image, its style, or a layout element is broken when being lazyloaded.
The background images are above the fold, and you need to load them instantly.

Technical details

The data-rocket-lazy-bg="loaded" attribute will be applied to the HTML elements with background images processed by this feature.
The background image URL will be replaced by a CSS variable which is paired to the background image URL. The CSS variable will have the --wpr-bg prefix.
This feature adds two internal styles to the page, as follows:
- The style with the wpr-lazyload-bg ID that, after the LazyLoad is executed, will contain the definition of the pair(s) of CSS variable and layloaded background image URL.
- The CSS block with the wpr-lazyload-bg-exclusion ID used to define the pair of CSS variable and URL for the excluded background images. This style is defined in the page source, ready to be used immediately on page load.
The two internal CSS blocks are required for the browser to find which background image URL is linked to which CSS variable, and render the HTML element with its corresponding background image.
Additionally, this feature adds three inline scripts to the optimized pages:
- A JSON block which uses the const rocket_pairs constant, and stores: the pair(s) of URL and CSS variable; and the ID of the HTML element linked to each pair.
- The script with the rocket_lazyload_css-js-extra ID, which is used to set the LazyLoad threshold. This threshold can be customized as shown here.
- The script with the rocket_lazyload_css-js-after ID, that's used to handle the lazyloading process by constantly checking the DOM elements present within the defined threshold, and further apply the replacements according to the information in the JSON block.
The rewritten CSS file(s) will be stored in the file system, under the /wp-content/cache/background-css/yourdomain.com/ folder. If you use WordPress Multisite, the folder named /1/ will change to reflect the site number to avoid mixing CSS files between sub-sites.

Known problems

The LazyLoad for CSS background images feature is not fully compatible with combined CSS third party features, so it's not recommended to use both at the same time.
The LazyLoad for CSS background images feature is not compatible with third party lazyloading of background images.