WordPress 5.5 has a built-in image lazy loading function. What are the requirements for developers?

Starting from WordPress 5.5, WordPress will use local HTML loadingattributes by default  to add delayed loading for images, which will greatly save server and bandwidth resources, improve website loading speed, and improve user experience.

By default, WordPress will add loading="lazy"to all tags with widthand heightattributes img. Technically speaking, this is handled on the page output, similar to how responsive images are achieved by adding srcsetand sizesattributes. In order to improve the server-side performance of these two functions, a new function is introduced wp_filter_content_tags(), so you only need to parse the imglabel once , and then postpone the modification of these functions to more specific functions.

For more details, see #44427.

Reducing layout offset is a prerequisite

A common user experience problem in modern websites is the so-called layout shifting, which is usually caused by slow loading of media resources such as images: by default, the browser can only lay out the page correctly after the image is loaded. Generate content, such as shifting below the picture. This problem can be easily solved imgby providing widthand heightattributes on the label , because the browser will use them to determine the aspect ratio of the image so that the page layout can be inferred before the image is actually loaded .

Although this is already the main problem with no lazy loading of images, it becomes even more important for lazy loading. Therefore, WordPress will only be added loading="lazy"to tags that have both widthand heightattributes img. At the same time, solving the fundamental problem is equally important for reducing the overall layout transfer, which is why WordPress 5.5 will automatically add these two attributes when the imgtag does not exist widthand the heightattribute. To do this, WordPress has rebuilt certain logic for determining srcsetand sizesattributes. Like these attributes, widthand heightcan only determine whether an image is used in a WordPress attachment and img whether the tag contains related wp-image-$idclasses.

WordPress has been following this best practice, and is working to ensure that all image editor has widthand height. As long as the theme’s CSS can work properly with the classic editor content, backfilling these properties will not have any impact on the theme. This is to be expected: if the image is modified widthor heightmodified by CSS, the corresponding other properties should be set autoto avoid the image being stretched.

For more background information on this change, see #50367.

Custom lazy loading

By default, WordPress will add loading="lazy"attributes to the following images :

  • Picture in article content ( the_content)
  • Picture in abstract ( the_excerpt)
  • Picture of text widget ( widget_text_content)
  • Profile picture ( get_avatar)
  • Use wp_get_attachment_image()the template image

Developers can customize this behavior through various filters. The most basic filter is wp_lazy_loading_enabledthat the filter receives the following parameters:

  • $default: Boolean default trueto filter.
  • $tag_name: HTML tag name. Although it is always the current WordPress behavior img, it should be noted that loadingattributes are universal attributes and may be expanded to support other elements in the future, for example iframe.
  • $context: The context string as an additional parameter indicates the technical origin of the image, usually the WordPress hook name. Depending on how WordPress itself uses lazy loading, the context can be one of the five values ​​in parentheses in the list of this article.

For example, if you want to turn off lazy loading of template images by default, you can use the following code snippet:

function disable_template_image_lazy_loading( $default, $tag_name, $context ) {
    if ( 'img' === $tag_name && 'wp_get_attachment_image' === $context ) {
        return false;
    return $default;

In order to modify the loading properties of non-specific images, there are two different methods, depending on the type of image:

That appear in the image-related content (e.g. the_content, , the_excerpt),widget_text_content another new filter is available wp_img_tag_add_loading_attr, which receives the following parameters:

  • $value: The attribute value being loaded, which can be ” lazy” (default), ” eager” or false. If you want to disable lazy loading of images, it is strongly recommended to set it to falseso that this property is completely omitted.
  • $image: The entire image HTML tags and their attributes.
  • $context: Context, similar to the other filters above.

For example, if you want to disable largethe lazy loading of a specific attachment image with an ID of 42 and a size of ” ” in the article content , you can use the following code snippet:

function skip_loading_lazy_image_42_large( $value, $image, $context ) {
    if ( 'the_content' === $context ) {
        $image_url = wp_get_attachment_image_url( 42, 'large' );
        if ( false !== strpos( $image, ' src="' . $image_url . '"' ) {
            return false;
    return $value;

For the wp_get_attachment_image()output image, the $attrattribute can be controlled simply by the parameter of the function , which can be the $valuesame possible value as the parameter of the above-mentioned filter. In order not to delay the loading of the image, the loadingattribute value should be specified false, which will cause the attribute to be ignored. E.g:

echo wp_get_attachment_image(
    array( 'loading' => false ),

It is recommended that theme developers refine their attributes wp_get_attachment_image()on images or other image-based functions (such as the_post_thumbnail()or  get_custom_logo()) loading, depending on where they are used in the template. For example, if the image is placed in the header.phptemplate and is likely to be in the initial viewport, it is recommended to skip the loadingproperties of the image.

Images marked as lazy loading candidate images require the browser to parse the position of the image on the page, which depends on the availability of IntersectionObserver, so their extraction has been slightly delayed from today. Experiments using the Android version of the Chrome browser show that such loading="lazy"images have little effect on the “Maximum Content Painting” indicator in the initial viewport, and are the 75th percentile and 99th percentile compared with non-lazy loading images. The percentile has a regression range of less than 1%, but this is a consideration that enables theme developers to apply some fine-tuning for a better user experience.

For more background information on this change, see #50425.

Browser compatibility

This loadingattribute is widely supported by modern browsers and is on the rise: for example, although Safari support is not available at the time of release, this feature is also being used and has been incorporated into the basic WebKit engine.

However, even loadingbrowsers that do not currently support this attribute will not see any negative effects of WordPress providing this attribute on images, because the native lazy loading mechanism is implemented as a fully progressive enhancement : for these browsers, this attribute will be ignored. This also means that whenever a browser implements support for this feature, its users will get immediate benefits when browsing a WordPress-powered site.

Leave a Reply

Your email address will not be published. Required fields are marked *