wp_img_tag_add_decoding_attr( string $image, string $context ): string

Adds decoding attribute to an img HTML tag.


The decoding attribute allows developers to indicate whether the browser can decode the image off the main thread (async), on the main thread (sync) or as determined by the browser (auto).

By default WordPress adds decoding="async" to images but developers can use the ‘wp_img_tag_add_decoding_attr’ filter to modify this to remove the attribute or set it to another accepted value.

Top ↑


$image string Required
The HTML img tag where the attribute should be added.
$context string Required
Additional context to pass to the filters.

Top ↑


string Converted img tag with decoding attribute added.

Top ↑


File: wp-includes/media.php. View all references

function wp_img_tag_add_decoding_attr( $image, $context ) {
	 * Filters the `decoding` attribute value to add to an image. Default `async`.
	 * Returning a falsey value will omit the attribute.
	 * @since 6.1.0
	 * @param string|false|null $value   The `decoding` attribute value. Returning a falsey value
	 *                                   will result in the attribute being omitted for the image.
	 *                                   Otherwise, it may be: 'async' (default), 'sync', or 'auto'.
	 * @param string            $image   The HTML `img` tag to be filtered.
	 * @param string            $context Additional context about how the function was called
	 *                                   or where the img tag is.
	$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;

Top ↑


Top ↑


Version Description
6.1.0 Introduced.

Top ↑

User Contributed Notes

You must log in before being able to contribute a note or feedback.