Refining WordPress core’s lazy-loading implementation

Since the image lazy-loading feature was originally added to WordPress core in 5.5, by default every post content image as well as every image rendering using the wp_get_attachment_image() function (which includes featured images) is lazy-loaded. This optimization follows the typical implementation of the feature in other projects, without consideration for whether an image appears above or below the fold. Due to the available metrics at the time it was decided to leave fine-grained control over opting out certain images from being lazy-loaded to theme authors, since the position of images heavily depends on the current theme layout. See also the following paragraph in the original announcement post:

Theme developers are recommended to granularly handle loading attributes for images anytime they rely on wp_get_attachment_image() or another function based on it (such as the_post_thumbnail() or get_custom_logo()), depending on where they are used within templates. For example, if an image is placed within the header.php template and is very likely to be in the initial viewport, it is advisable to skip the loading attribute for that image.

It was recently discovered that the current WordPress core implementation of lazy-loading has room for improvement as it can regress the Largest Contentful Paint metric (LCP) when hero images above the fold are being lazy-loaded. Therefore, the default behavior of the existing lazy-loading implementation should be refined in order to better take this nuance into account.

Omitting the loading attribute on certain elements

As mentioned before, WordPress coreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress. is unable to reliably assess whether an image is going to appear above or below the fold, since it depends on the currently active theme. Furthermore, the loading attributes are added on the server-side, which has no notion on the influencing client factors like viewport size. Because of those reasons, fine-grained control over lazy-loading images (and iframes) still remains with theme authors. However, we can fine tune WordPress core’s lazy-loading implementation to behave in a way that improves the situation for the vast majority of cases, to achieve better LCP values out of the box.

Now, one could argue that lazy-loading should be entirely removed again to avoid any negative impact on LCP. However, that would also remove all the benefits that lazy-loading comes with, which is reducing bandwidth and wasting fewer networknetwork (versus site, blog) resources, which in itself can impact Core Web Vitals (CWV) metrics. The preferable default behavior here would be to find a solid middle ground between those trade-offs. This leads to the following goal for the WordPress core implementation:

The first “x” content image(s) should not be lazy-loaded by default, with “x” being as high as possible so that there is little to no LCP regressionregression A software bug that breaks or degrades something that previously worked. Regressions are often treated as critical bugs or blockers. Recent regressions may be given higher priorities. A "3.6 regression" would be a bug in 3.6 that worked as intended in 3.5. and as low as possible so that there is little to no regression in the total bytes loaded.

(Note that this also includes iframes, but they are less commonly used as hero elements, so for simplicity this post mentions primarily images.)

To determine the right value for “x” (i.e. the number of images/iframes to omit from being lazy-loaded by default), I conducted an analysis using two versions of a small prototype pluginPlugin A plugin is a piece of software containing a group of functions that can be added to a WordPress website. They can extend functionality or add new features to your WordPress websites. WordPress plugins are written in the PHP programming language and integrate seamlessly with WordPress. These can be free in the WordPress.org Plugin Directory https://wordpress.org/plugins/ or can be cost-based plugin from a third-party which prevents the loading=”lazy” attribute from being added to the first 1 or 2 content images respectively. The analysis relied on the following methodology:

• Test across the 50 most popular themes according to the wordpress.orgWordPress.org The community site where WordPress code is created and shared by the users. This is where you can download the source code for WordPress core, plugins and themes as well as the central location for community conversations and organization. https://wordpress.org/ popular themes search
• Test on a demo site without any plugins active (except for the lazy-loading prototype plugin), for an archive view with 5 posts (where every post has a featured imageFeatured image A featured image is the main image used on your blog archive page and is pulled when the post or page is shared on social media. The image can be used to display in widget areas on your site or in a summary list of posts.) and for a single post view (where the post has a featured image as well as 5 images within its content), i.e. 2 different types of URLs
• Test for 2 viewports, “mobile” and “desktop”
• Use WebPageTest for the individual scenarios (200 in total), with 9 test runs for each scenario in order to counter variance and rely on the median result

That analysis produced the following results:

• Omitting the first content image from being lazy-loaded resulted in a median LCP improvement of 7% (1,877ms compared to 2,020ms with current core behavior) and a median image bytes increase of 0% (368KB compared to 369KB with current core behavior). → Omitting the first content image clearly results in an LCP improvement while not noticeably regressing on image bytes saved.
• Omitting the first two content images from being lazy-loaded resulted in a median LCP improvement of 5% (1,927ms compared to 2,020ms with current core behavior) and a median image bytes increase of 2% (378KB compared to 369KB with current core behavior). → Omitting the first two content images produces worse results for both metrics than only omitting the first one, i.e. it is better to only skip lazy-loading for the first content image, and therefore no additional tests with larger numbers of images not being lazy-loading are needed.
• Both fixes actually perform even better in LCP compared to the results with lazy-loading completely disabled. This confirms that completely disabling lazy-loading is not a solution to the problem.
• Drilling further into the results for omitting the first content image, 42% of scenarios result in a median LCP improvement of greater than 10%, with the maximum improvement being 33%. 5% of scenarios result in the median LCP being more than 10% worse, with the maximum here being 21%. → While the median LCP improvement across all themes is only 7%, there are larger notable wins for a significant number of themes, while notable losses are minimal.

Following up on the findings on the LCP regression from lazy-loading as well as the analysis about the potential fix, the following refinement to the lazy-loading implementation in core is being proposed for WordPress 5.9:

• Instead of lazy-loading all images and iframes by default, the very first content image (also considering featured images) or content iframeiframe iFrame is an acronym for an inline frame. An iFrame is used inside a webpage to load another HTML document and render it. This HTML document may also contain JavaScript and/or CSS which is loaded at the time when iframe tag is parsed by the user’s browser. should not be lazy-loaded.
• This is a more sensitive default than what the current implementation uses, that on average and at scale will result in better LCP performance out of the box, while keeping necessary bandwidth low.
• Despite this change of the default behavior, responsibility for fine grained control of which elements should be lazy-loaded remains with theme authors. As a theme author, you are still recommended to specify a loading attribute value for images presented by the theme. Particularly pay attention if your theme relies on less standard layouts, e.g. a grid or slider view of posts or if post content only appears far down the page.

A TracTrac An open source project by Edgewall Software that serves as a bug tracker and project management tool for WordPress. ticketticket Created for both bug reports and feature development on the bug tracker. for adding this enhancementenhancement Enhancements are simple improvements to WordPress, such as the addition of a hook, a new feature, or an improvement to an existing feature. to core has been opened in #53675 for further review and discussion.

Props to @addyosmani, @adamsilverstein, @desrosj for review and proofreading.

#feature-lazyloading