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:
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:
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 thedata-rocket-lazy-bg="loaded"
attribute.
For example, the markup of ap
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:
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 style with the
- 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.
- A JSON block which uses the
- 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.