Remove Async Decoding from WordPress Images

WordPress 6.1 introduced a new core functionality which adds a new decoding attribute decoding="async" to all images returned by the core WordPress thumbnail functions as well as the image block.

What is Async Decoding?

Before removing or changing the decoding attribute it’s important to understand why it was added in WordPress core and what it does exactly. The decoding property of an image provides a hint to the browser on how it should decode the image. Put simply, it tells the browser if it should wait for an image to be decoded before moving onto the next html or if it can load the image in parallel with other content on the site.

Decoding Types: Sync vs Async

The decoding attribute accepts 3 values: sync, async or auto.

Auto: This is the default value if the attribute is not present and it allows the browser to do whatever it thinks is best for the user.

Sync: Decode the image synchronously. You have probably heard of the term “render-blocking” which is what async is, basically nothing else on the site will be decoded until the image has been decoded.

Async: Decode the image asynchronously. This means the image can be decoded while other content of the site is also decoded thus reducing the delay in presenting other content, aka, “non-blocking”.

Why was it added in WordPress?

If you have a look at the WordPress 6.1 performance field guide the don’t really mention why it was implemented but they link to the original ticket with the following:

Recently I have been playing around with another special attribute to the img tag which is basically decoding="async". After implementing async decoding to the images in a page, the page load became, even more, faster and images are decoded asynchronously by the browser, loading the contents almost instantly and also reducing page render time. This is a huge performance booster to any webpages which has a lot of images (so basically most sites).

view source

Since WordPress has released many updates with speed in mind it made perfect sense to implement this new image decoding attribute to significantly increase site loading on pages with a lot of images.

How to Disable decoding="async" in WordPress?

Now that you know what async decoding is and why it was implemented (for speed) perhaps you don’t want to remove it anymore but if you still do (perhaps it’s conflicting with something) keep on reading as I will show you how.

Disable the decoding attribute globally

The following snippet, which can be added to your child theme functions.php file or via a plugin such as the Code Snippets plugin, will completely remove the attribute from all images on the site.

// Removes the decoding attribute from images added inside post content.
add_filter( 'wp_img_tag_add_decoding_attr', '__return_false' );

// Remove the decoding attribute from featured images and the Post Image block.
add_filter( 'wp_get_attachment_image_attributes', function( $attributes ) {
    unset( $attributes['decoding'] );
    return $attributes;
} );

Disable the decoding attribute conditionally

But what if you only wanted to disable the decoding attribute from certain images? Unfortunately there is no built-in way to do this. Hopefully in the future WordPress will at least add the option to the Gutenberg image and post image blocks, but for now there is nothing available.

That said, it’s possible to conditionally remove the attribute using code if you are targeting featured images. When a featured image (thumbnail) is displayed in a theme or plugin (assuming it’s using core WP functions) it can pass custom arguments so one way to disable the attribute is by updating the attributes passed on to the_post_thumbnail function like such:

add_action( 'wp_body_open', function() {
    the_post_thumbnail( 'full', [
        'decoding' => false, // remove the decoding attribute
        'loading' => false, // optionally remove lazy loading
    ] );
} );

If you are working with a 3rd party product most likely you can’t just update the_post_thumbnail function to modify the arguments, but you can still hook into the wp_get_attachment_image_attributes filter. Lets say if your site is displaying a featured image with the classname high-priority-img you could add some code that checks the image attributes for the specific classname and if it exists it removes the decoding attribute.

/**
 * Remove the decoding attribute from images with the classname "high-priority-img"
 */
add_filter( 'wp_get_attachment_image_attributes', function( $attributes ) {
    if ( isset( $attributes['class'] ) && false !== strpos( $attributes['class'], 'igh-priority-img' ) ) {
        unset( $attributes['decoding'] );
    }
    return $attributes;
} );

Perhaps you aren’t working with custom classnames but rather using fetchpriority="high" we can check for that as well like such:

/**
 * Remove the decoding attribute from images with a high fetchpriority.
 */
add_filter( 'wp_get_attachment_image_attributes', function( $attributes ) {
    if ( isset( $attributes['fetchpriority'] ) && 'high' === $attributes['fetchpriority'] ) {
        unset( $attributes['decoding'] );
    }
    return $attributes;
} );

I hope this guide was useful and if you have any questions let me know in the comments below!