wp_img_tag_add_decoding_attr() │ WP 6.1.0

Deprecated since 6.4.0. It is no longer supported and may be removed in future releases. Use wp_img_tag_add_loading_optimization_attrs() instead.

Adds the attribute decoding="async" to all images (tag <img>) in the provided text.

The decoding attribute allows you to specify how the browser should decode the image:

  • async - outside the main thread.
  • sync - in the main thread.
  • auto - according to the browser's logic.

In version 6.1 WordPress adds decoding="async" to all images. The current function is called in the function wp_filter_content_tags(), which is forcefully hooked on:

add_filter( 'the_content', 'wp_filter_content_tags' );
add_filter( 'the_excerpt', 'wp_filter_content_tags' );
add_filter( 'widget_text_content', 'wp_filter_content_tags' );
add_filter( 'widget_block_content', 'wp_filter_content_tags' );

decoding and lazy load are different things. decoding is related to how the browser decodes the image data, not when it loads them. That is, the image is first loaded (in encoded form), then decoded, and only then displayed. By default, decoding occurs in the main thread, which can interfere with other processes happening on the page.

The decoding attribute and its value async

With decoding=async you inform the browser that the image can be interpreted asynchronously, i.e., decoded in a parallel thread, and should not affect the main rendering thread of the page.

Important: during the loading process, the browser skips the image area, not knowing what size to leave for it, and renders what comes below. At the same time, in a parallel thread, it loads the image, learns its dimensions, and fits it into the page. And when the image is loaded, the layout may jump.

Characteristic CLS (Cumulative Layout Shift)

Until the last update, these shifts in content during image loading did not concern Google specialists. But now a new characteristic has appeared - CLS - which measures the content shift during loading.

Therefore, it is now necessary to ensure that the people responsible for the layout correctly reserve space for the image, accurately specifying the dimensions or proportions of the image. So that when the image is loading, there is no jarring of this content up and down.

Neither the quality of the images nor their size affects your scores in pagespeed. It is the load they create that matters. And this load can be mitigated by adding: decoding=async.

Source: https://www.seonews.ru/analytics/kak-zanyat-top-pri-pomoshchi-odnogo-izobrazheniya/

To change the value of the decoding attribute, use the hook: wp_img_tag_add_decoding_attr.

Useful links on the topic:

1 time — 0.0000272 sec (very fast) | 50000 times — 0.10 sec (speed of light) | PHP 7.4.33, WP 6.1.1
Hooks from the function

Returns

String. Text in which the img has the decoding attribute added.

Usage

wp_img_tag_add_decoding_attr( $image, $context );
$image(string) (required)
Text in which there are <img> tags to which the decoding attribute needs to be added.
$context(string) (required)
Context from which the function is triggered, passed to the hook filter.

Examples

Notes

Changelog

Since 6.1.0 Introduced.
Deprecated since 6.4.0 Use wp_img_tag_add_loading_optimization_attrs() instead.

wp_img_tag_add_decoding_attr() code WP 6.8.3

wp-includes/deprecated.php 
function wp_img_tag_add_decoding_attr( $image, $context ) {
	_deprecated_function( __FUNCTION__, '6.4.0', 'wp_img_tag_add_loading_optimization_attrs()' );

	/*
	 * Only apply the decoding attribute to images that have a src attribute that
	 * starts with a double quote, ensuring escaped JSON is also excluded.
	 */
	if ( ! str_contains( $image, ' src="' ) ) {
		return $image;
	}

	/** This action is documented in wp-includes/media.php */
	$value = apply_filters( 'wp_img_tag_add_decoding_attr', 'async', $image, $context );

	if ( in_array( $value, array( 'async', 'sync', 'auto' ), true ) ) {
		$image = str_replace( '<img ', '<img decoding="' . esc_attr( $value ) . '" ', $image );
	}

	return $image;
}