Automatic Lazy Rendering

WP Rocket 3.17 introduces a feature called Automatic Lazy Rendering, which delays the rendering of distant elements from the fold, in order to display the above the fold elements faster.

Those below the fold elements will be rendered only when visitors scroll down the page.

This optimization is automatically enabled upon WP Rocket activation, therefore, it doesn't have any option or button in the settings page.

Note! The process of detecting which elements need to be lazily rendered is automatic but not immediate, it's asynchronous.

In this article, you can find more information about how this feature works, how to check if it's working, how to fix common issues, and other relevant information.

Feature overview

The Automatic Lazy Rendering option automatically detects the elements distant from the fold, then uses CSS to instruct the browser to delay their rendering until the visitor scrolls down the page and the elements are within the viewport. We will apply the optimization only to the following HTML elements:

div
main
footer
section
article
header

Different lazily rendered elements for mobile and desktop

To provide an accurate delaying of the elements, the mobile and desktop versions of a page are processed, and their specific elements are optimized independently.

This behavior depends on the Mobile Cache option, which creates a mobile-specific version of the cache by default. Therefore, the Mobile Cache option, and its mobile-specific behavior, should not be deactivated.

Asynchronous approach

The Automatic Lazy Rendering option works asynchronously this way:

An identifier will be added to the elements of a page.
Also, a script will be injected to the page.
Upon a visit, WP Rocket executes the script that detects which of the identified elements are distant from the fold.
The next time the page is cached, the markup of below the fold elements will be modified, and they will be lazily rendered.

Feature benefits

The goal of the Automatic Lazy Rendering feature is to speed up the process of rendering the page, providing users a faster perceived loading time, and give better chances to respond faster to interaction.

Elements which are not critical on a page, such as the footer, will only be rendered if the user scrolls down the page and really needs to see them.

Benefits for PageSpeed/Lighthouse

With this feature, you can expect certain improvements around these metrics and audits:

Note! The improvements are especially noticeable on pages that contain several elements that had been lazily rendered.

How to use the Automatic Lazy Rendering feature

The Automatic Lazy Rendering option is activated by default, and it's automatic, but to make sure the whole asynchronous process happens as fast as possible, it's recommended to use it along with the Remove Unused CSS option.

If you can't activate the Remove Unused CSS feature, you should mind the following points:

For the script to be executed, and for the process of detecting and retrieving data to be successful, the type of visit made to the page needs to provide valid information about the elements inside and outside the browser viewport.

This type of valid visit happens when:
- A real user visits the page with a browser within the required dimensions.
- The page is processed by the Remove Unused CSS SaaS during Used CSS generation.
- Or, if the Remove Unused CSS option is not active, a pre-warmup process will happen to execute the script for 10 of your site's pages.
After the script is executed and the detection of elements is finished, the cache needs to be cleared manually or automatically.

After the cache is cleared at this point, the below the fold elements will have the markup that will lazily render them.

Basic requirements

The Automatic Lazy Rendering option has these basic requirements:

Your server, firewall, and/or security plugin has to allow-list (or at least not block) AJAX requests coming from the frontend and wp-admin/admin-ajax.php.
PHP DOM extension must be enabled on your server. If it's not active, you'll encounter a 500 error in the browser console and a PHP fatal error in the logs: PHP Fatal error: Uncaught Error: Class "DOMDocument" not found. If you cannot enable the extension, disable Automatic Lazy Rendering with this helper plugin.
The IPs found in this list should be allowed in the server, firewall, and/or security plugin.
When used along with the Remove Unused CSS option (recommended), the same basic requirements should be met.

If WP Rocket can't access your site, the following admin notice will be displayed:

firewall block admin notice

It seems a security plugin or the server's firewall prevents WP Rocket from accessing the SaaS features. IPs listed here in our documentation should be added to your allowlists:

- In the security plugin, if you are using one
- In the server's firewall. Your host can help you with this

Pre-warmup

To speed up the processing of some pages, the Automatic Lazy Rendering option uses a pre-warmup system, which works as follows:

The first 10 URLs found in the mobile homepage will be sent to WP Rocket's Optimize critical images SaaS. The rest of the pages will be processed as they are visited.
The SaaS will open those links using real browser and the data will be generated by the script.
SaaS will visit the URLs with ?wpr_imagedimensions=1&nowprocket=1&no_optimize=1 query string added.

Pre-warmup will not happen when:

Remove Unused CSS is enabled, because the URLs visited by the Used CSS generation SaaS will trigger the script, and generate the data automatically.
The access to the ?wpr_imagedimensions=1&nowprocket=1&no_optimize=1 query string is blocked.
The WP_ENVIRONMENT_TYPE constant is set to local.
The license is expired for more than 15 days.

How to check if Automatic Lazy Rendering is working

Here's how you can tell if the elements of a page are still being processed, or if they are already optimized by the Automatic Lazy Rendering feature.

The page is being processed

If the optimization of a page has started, the HTML elements of the page will use the data-rocket-location-hash attribute, with a unique value, like this:

<div data-rocket-location-hash="aa11bb22" class="wp-block-group" style="padding-top:0" >

The aa11bb22 unique value is a hash that identifies each element.

Also, the wpr-beacon.min.js script will be present in the source code.

The script can be found with following markup:

<script data-name="wpr-wpr-beacon" src='https://yoursite.com/wp-content/plugins/wp-rocket/assets/js/wpr-beacon.min.js' async></script>

If the elements of a page use the data-rocket-location-hash attribute, or a page contains the wpr-beacon.min.js script, it means the optimization has started.

The page is already processed

Then, you can tell if the page was already processed when the HTML elements, which are effectively located below the fold, use the data-wpr-lazyrender="1" attribute.

An element that is lazily rendered has the following markup:

<footer data-wpr-lazyrender="1" class="wp-block-group">

Additionally, this inline CSS block will be added to the page, which is used for the browser to execute the lazy rendering:

<style id="rocket-lazyrender-inline-css">[data-wpr-lazyrender] {content-visibility: auto;}</style>

Elements with the data-wpr-lazyrender="1" attribute have been correctly lazily rendered.

Automatic clearing of lazily rendered elements

WP Rocket will automatically clear the lazily rendered elements:

When permalinks are changed, all the elements will be purged.
When the theme is switched, all elements will be cleared.
When updating the post, the post-specific elements will be cleared. This doesn't apply for the elements in the related pages.

Manual clearing of lazily rendered elements

When you make manual changes to the content of your pages, you should manually clear the elements via the WP Rocket toolbar menu.

To clear the elements of all your site, from the top menu you can click on the button called Clear Priority Elements, this one:

clear-priority-elements-button

To clear the elements of a specific post, you can click on the Clear Priority Elements of this URL, like this:

clear-priority-elements-of-this-url-button

Note: The Clear Priority Elements option clears both the lazily rendered elements, and the critical images from the Optimize critical images feature.

How to exclude elements from this feature

In case you need to exclude certain elements from this optimization because they are being negatively affected by it, you can use the following helper plugin:

📥 Download (.zip): WP Rocket | Exclude specific elements from Automatic Lazy Rendering
Developers: You can find the code for this plugin on GitHub.

Heads up! Manual code edit required before use!

After downloading the plugin zip file, unzip it and open the PHP file in a text editor.
Look for the attributes of the HTML tag you want to exclude, and choose any attribute that's unique.

Replace this line with the real element attribute you want to exclude:
```
$exclusions[] = 'main-footer"';
	
```
If you need to exclude more elements, you may keep adding as many lines as necessary.
After making your edits, save the PHP file and re-zip the plugin.
In your WordPress site, go to Plugins > Add New > Upload Plugin and upload the zip file.
Activate it and clear the cache.

How to deactivate this feature
If this optimization causes problems, and you want to deactivate it, please install and activate the following helper plugin:
📥 Download (.zip): WP Rocket | Disable Automatic Lazy Rendering
Developers: You can find the code for this plugin on GitHub.
Alternatively, you can add to your site the following snippet:
```
add_filter( 'rocket_lrc_optimization', '__return_false' , 999);
	
```
Known conflicts
- Additional layers of cache that don't differentiate between device type
  
  If the site is using additional layers of cache that don't differentiate between mobile and desktop devices, this optimization may have problems when detecting and optimizing the below the fold elements.
  
  As a result, it's possible that the mobile-specific elements appear optimized in the desktop version of the page, or the other way around.
  
  Solution: The only known solution is to deactivate any layers of cache that don't use specific cache for device type.
- Lazily rendered elements are mixed up for mobile and desktop
  
  This problem can happen if the Mobile Cache option, and/or its mobile-specific cache feature, are deactivated.
  
  Solution: Ideally, enable the Mobile Cache option again. However, if the Mobile Cache, or its mobile-specific cache feature, need to be kept deactivated on a site, the Automatic Lazy Rendering feature should be deactivated too. You can do this with this helper plugin.
Troubleshooting
If the wpr-beacon.min.js script is correctly added to a page, but the elements are not optimized yet, a common solution is to clear the cache of WP Rocket and any other cache layer(s) running on the site.
If clearing the cache doesn't help, it could be that the script wasn't executed yet. In this case, make sure a visit is being made within the required dimensions.

Technical notes
- The wpr-beacon.min.js script will only collect data after a visit was made with a browser with the following dimensions:
  - Mobile devices with display area smaller than 393x830.
  - Desktop devices with display area bigger than 1600x700.
    
    For visits made outside the above dimensions, WP Rocket will consider that the type of device used is too large or too small, and the script will not be executed.
- The wpr-beacon.min.js script can't be executed on headless browsers.
- The data collected by the script is stored in the wpr_lazy_render_content table.
- The HTML elements will be processed when their depth is maximum 3 starting from the body element.
- The HTML elements will be lazily rendered if they are located at a 1800px distance below the fold.
- The Action Scheduler task, called rocket_job_warmup, will be created to fetch the mobile homepage and send each of the 10 URLs to the pre-warmup process.
If you have additional questions, you can contact WP Rocket's support team.