Reduce maximum image size used as background image based on container width by nani-samireddy · Pull Request #2258 · WordPress/performance

nani-samireddy · 2025-11-08T03:23:28Z

Summary

Relevant technical choices

This change exposes background image attachment IDs and original URLs from block attributes (core/group and core/cover) as data attributes on the rendered HTML element, and uses those attributes in Image Prioritizer to pick and serve a more appropriate-sized background image. It enables downsizing background images based on collected URL Metrics (preferring desktop metrics to avoid serving overly small images to desktop visitors).

Use of AI Tools

…ml tag attributes

…idth

… enhancement/reduce-maximum-image-size-used-as-background-image

codecov · 2025-11-08T03:35:24Z

Codecov Report

❌ Patch coverage is 81.13208% with 10 lines in your changes missing coverage. Please review.
✅ Project coverage is 69.37%. Comparing base (695d5b8) to head (4c1d7f2).

Files with missing lines	Patch %	Lines
...rioritizer-background-image-styled-tag-visitor.php	57.14%	6 Missing ⚠️
...ns/auto-sizes/includes/improve-calculate-sizes.php	85.18%	4 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##            trunk    #2258      +/-   ##
==========================================
+ Coverage   69.32%   69.37%   +0.04%     
==========================================
  Files          90       90              
  Lines        7746     7791      +45     
==========================================
+ Hits         5370     5405      +35     
- Misses       2376     2386      +10

Flag	Coverage Δ
multisite	`69.37% <81.13%> (+0.04%)`	⬆️
single	`35.79% <43.39%> (+0.08%)`	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

github-actions · 2025-11-08T06:48:41Z

The following accounts have interacted with this PR and/or linked issues. I will continue to update these lists as activity occurs. You can also manually ask me to refresh this list by adding the props-bot label.

If you're merging code through a pull request on GitHub, copy and paste the following into the bottom of the merge commit message.

Co-authored-by: nani-samireddy <nanisamireddy@git.wordpress.org>
Co-authored-by: westonruter <westonruter@git.wordpress.org>

To understand the WordPress project's expectations around crediting contributors, please review the Contributor Attribution page in the Core Handbook.

…as-background-image

Updated the PHP docblock for clarity and consistency.

Copilot

Pull request overview

This PR implements background image size optimization for core/group and core/cover blocks by exposing attachment IDs as data attributes and using URL Metrics to serve appropriately-sized images based on container dimensions.

Changes:

Added auto_sizes_add_background_image_data_attributes function to extract and expose background image attachment IDs and URLs as data attributes on rendered HTML elements
Implemented reduce_background_image_size method in Image Prioritizer to downsize background images based on desktop viewport metrics
Registered new filter hooks for core/group and core/cover blocks at priority 5

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 5 comments.

File	Description
plugins/image-prioritizer/class-image-prioritizer-background-image-styled-tag-visitor.php	Added method to reduce background image sizes using attachment IDs from data attributes and URL Metrics
plugins/auto-sizes/includes/improve-calculate-sizes.php	Added function to extract background image data from block attributes and add as data attributes to HTML
plugins/auto-sizes/hooks.php	Registered filter hooks for core/group and core/cover blocks to add background image data attributes

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2026-01-15T00:16:05Z

plugins/image-prioritizer/class-image-prioritizer-background-image-styled-tag-visitor.php

+				// Replace the background image URL in the style attribute.
+				$style = $processor->get_attribute( 'style' );
+				if ( is_string( $style ) ) {
+					$updated_style = str_replace( $background_image_url, $smaller_image_url, $style );


The str_replace approach could potentially replace unintended occurrences if the same URL appears multiple times in the style attribute. While unlikely in practice, consider using a more targeted replacement that specifically replaces within the background-image or background property. Alternatively, verify that this edge case is acceptable for the intended use cases.

Suggested change

// Replace the background image URL in the style attribute.

$style = $processor->get_attribute( 'style' );

if ( is_string( $style ) ) {

$updated_style = str_replace( $background_image_url, $smaller_image_url, $style );

// Replace the background image URL in the background/background-image declarations in the style attribute.

$style = $processor->get_attribute( 'style' );

if ( is_string( $style ) ) {

$declarations = explode( ';', $style );

foreach ( $declarations as &$declaration ) {

$trimmed_declaration = ltrim( $declaration );

if (

0 === stripos( $trimmed_declaration, 'background:' ) ||

0 === stripos( $trimmed_declaration, 'background-image:' )

) {

$declaration = str_replace( $background_image_url, $smaller_image_url, $declaration );

}

}

unset( $declaration );

$updated_style = implode( ';', $declarations );

Copilot · 2026-01-15T00:16:05Z

plugins/image-prioritizer/class-image-prioritizer-background-image-styled-tag-visitor.php

+	private function reduce_background_image_size( string $background_image_url, OD_Tag_Visitor_Context $context ): void {
+		$processor = $context->processor;
+		$xpath     = $processor->get_xpath();
+
+		/*
+		 * Obtain maximum width of the element exclusively from the URL Metrics group with the widest viewport width,
+		 * which would be desktop. This prevents the situation where if URL Metrics have only so far been gathered for
+		 * mobile viewports that an excessively-small background image would end up getting served to the first desktop visitor.
+		 */
+		$max_element_width = 0;
+		foreach ( $context->url_metric_group_collection->get_last_group() as $url_metric ) {
+			foreach ( $url_metric->get_elements() as $element ) {
+				if ( $element->get_xpath() === $xpath ) {
+					$max_element_width = max( $max_element_width, $element->get_bounding_client_rect()['width'] );
+					break;
+				}
+			}
+		}
+
+		// If the element wasn't present in any URL Metrics gathered for desktop, then abort downsizing the background image.
+		if ( 0 === $max_element_width ) {
+			return;
+		}
+
+		// Try to get the attachment ID from the data attribute (populated via filter from block attributes).
+		$attachment_id = $processor->get_attribute( 'data-bg-attachment-id' );
+
+		if ( is_numeric( $attachment_id ) && $attachment_id > 0 ) {
+			$smaller_image_url = wp_get_attachment_image_url( (int) $attachment_id, array( (int) $max_element_width, 0 ) );
+			if ( is_string( $smaller_image_url ) && $smaller_image_url !== $background_image_url ) {
+				// Replace the background image URL in the style attribute.
+				$style = $processor->get_attribute( 'style' );
+				if ( is_string( $style ) ) {
+					$updated_style = str_replace( $background_image_url, $smaller_image_url, $style );
+					$processor->set_attribute( 'style', $updated_style );
+				}
+			}
+		}
+	}


The new reduce_background_image_size method lacks test coverage. Consider adding snapshot tests similar to the existing video poster tests (e.g., video-with-large-poster-and-desktop-url-metrics-collected) to verify the background image size reduction functionality works correctly.

Copilot · 2026-01-15T00:16:05Z

plugins/auto-sizes/includes/improve-calculate-sizes.php

+function auto_sizes_add_background_image_data_attributes( $content, array $parsed_block ): string {
+	if ( ! is_string( $content ) || '' === $content ) {
+		return '';
+	}
+
+	$block_name = $parsed_block['blockName'] ?? '';
+	$attrs      = $parsed_block['attrs'] ?? array();
+
+	// Extract background image data based on block type.
+	$attachment_id = null;
+	$image_url     = null;
+
+	if ( 'core/cover' === $block_name ) {
+		$attachment_id = $attrs['id'] ?? null;
+		$image_url     = $attrs['url'] ?? null;
+	} elseif ( 'core/group' === $block_name ) {
+		$attachment_id = $attrs['style']['background']['backgroundImage']['id'] ?? null;
+		$image_url     = $attrs['style']['background']['backgroundImage']['url'] ?? null;
+	} else {
+		return $content;
+	}
+
+	// Validate extracted data.
+	if (
+		! isset( $attachment_id, $image_url ) ||
+		$attachment_id <= 0 ||
+		'' === $image_url ||
+		! is_array( wp_get_attachment_metadata( $attachment_id ) )
+	) {
+		return $content;
+	}
+
+	// Find and update the element with background image.
+	$processor = new WP_HTML_Tag_Processor( $content );
+	while ( $processor->next_tag() ) {
+		$style = $processor->get_attribute( 'style' );
+		if ( is_string( $style ) && str_contains( $style, 'background-image:' ) && str_contains( $style, $image_url ) ) {
+			$processor->set_attribute( 'data-bg-attachment-id', (string) $attachment_id );
+			$processor->set_attribute( 'data-bg-original-url', $image_url );
+			return $processor->get_updated_html();
+		}
+	}
+
+	return $content;
+}


The new auto_sizes_add_background_image_data_attributes function lacks test coverage. The auto-sizes plugin has comprehensive tests in test-improve-calculate-sizes.php. Consider adding unit tests to verify that data attributes are correctly added to Group and Cover blocks with background images.

plugins/auto-sizes/includes/improve-calculate-sizes.php

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

…lify return logic Consolidate multiple return statements into a single return at the end of auto_sizes_add_background_image_data_attributes(), keeping only the initial guard clause. Co-authored-by: gemini-cli <176961590+gemini-code-assist[bot]@users.noreply.github.com>

Consolidate duplicated logic for obtaining maximum element width into a protected method in the parent Image_Prioritizer_Tag_Visitor class. The new method returns null if the element is not found, providing a more robust check in subclasses. Co-authored-by: gemini-cli <176961590+gemini-code-assist[bot]@users.noreply.github.com>

… enhancement/reduce-maximum-image-size-used-as-background-image

westonruter

Sorry for the long delay in following up on this.

westonruter · 2026-02-26T23:22:44Z

plugins/image-prioritizer/class-image-prioritizer-background-image-styled-tag-visitor.php

+		// Try to get the attachment ID from the data attribute (populated via filter from block attributes).
+		$attachment_id = $processor->get_attribute( 'data-bg-attachment-id' );


There is a plugin dependency issue here. Currently this requires that the auto-sizes plugin be active in order for this attribute to be added. This dependency shouldn't exist. This attribute should be added in the Image Prioritizer plugin for its own use. If the Image Prioritizer plugin isn't active, then the auto-sizes plugin should be able to scale down the image all on its own because it has access to template layout information on its own. The Image Prioritizer implementation is a parallel one which will benefit sites without auto-sizes active, or sites which are using a classic theme in which case the layout information is not available.

westonruter · 2026-02-26T23:27:38Z

plugins/auto-sizes/includes/improve-calculate-sizes.php

+		while ( $processor->next_tag() ) {
+			$style = $processor->get_attribute( 'style' );
+			if ( is_string( $style ) && str_contains( $style, 'background-image:' ) && str_contains( $style, $image_url ) ) {
+				$processor->set_attribute( 'data-bg-attachment-id', (string) $attachment_id );


As noted below, this attribute is being added here exclusively for the use of another plugin: Image Prioritizer. This dependency needs to be removed. Instead, this needs to be determining the size of the block as informed by the layout it has access to based on the block structure on a block template.

In other words, I believe all of the logic here in auto_sizes_filter_render_block_context() needs to be re-factored into auto_sizes_filter_uses_context(), auto_sizes_filter_render_block_context(), and auto_sizes_filter_image_tag(), for example, to follow the pattern of how other blocks are currently handled.

westonruter · 2026-02-26T23:31:50Z

plugins/auto-sizes/hooks.php

+add_filter( 'render_block_core/group', 'auto_sizes_add_background_image_data_attributes', 5, 2 );
+add_filter( 'render_block_core/cover', 'auto_sizes_add_background_image_data_attributes', 5, 2 );


Taking auto_sizes_filter_image_tag() for inspiration, something like:

Suggested change

add_filter( 'render_block_core/group', 'auto_sizes_add_background_image_data_attributes', 5, 2 );

add_filter( 'render_block_core/cover', 'auto_sizes_add_background_image_data_attributes', 5, 2 );

add_filter( 'render_block_core/group', 'auto_sizes_filter_background_image_style', 5, 2 );

add_filter( 'render_block_core/cover', 'auto_sizes_filter_background_image_style', 5, 2 );

A new auto_sizes_filter_background_image_style() function will be needed modeled after auto_sizes_filter_image_tag().

nani-samireddy added 3 commits November 8, 2025 08:48

add: utility function to add attachment_id and original_url to the ht…

a985956

…ml tag attributes

enhancement: update the background image url based on the container w…

dfa6c45

…idth

Merge branch 'trunk' of github.com:nani-samireddy/wp-performance into…

5ed9644

… enhancement/reduce-maximum-image-size-used-as-background-image

nani-samireddy marked this pull request as ready for review November 8, 2025 06:48

nani-samireddy requested review from felixarntz, joemcgill, mukeshpanchal27 and westonruter as code owners November 8, 2025 06:48

nani-samireddy mentioned this pull request Nov 8, 2025

Reduce maximum image size used as background image based on container width #2216

Open

westonruter added this to the auto-sizes n.e.x.t milestone Jan 15, 2026

Merge branch 'trunk' into enhancement/reduce-maximum-image-size-used-…

ea61a9c

…as-background-image

westonruter changed the title ~~Enhancement: reduce maximum image size used as background image based on container width~~ Enhanced Responsive Images: Reduce maximum image size used as background image based on container width Jan 15, 2026

westonruter added 4 commits January 14, 2026 16:08

Add since tag

3fc31d1

Fix placement of since tag

134af1c

Updated the PHP docblock for clarity and consistency.

Add missing line break

cf42623

Fix indentation and add missing since tag

f49fdc6

westonruter added the [Plugin] Image Prioritizer Issues for the Image Prioritizer plugin (dependent on Optimization Detective) label Jan 15, 2026

westonruter changed the title ~~Enhanced Responsive Images: Reduce maximum image size used as background image based on container width~~ Reduce maximum image size used as background image based on container width Jan 15, 2026

westonruter requested a review from Copilot January 15, 2026 00:11

Copilot started reviewing on behalf of westonruter January 15, 2026 00:11 View session

Copilot AI reviewed Jan 15, 2026

View reviewed changes

westonruter and others added 3 commits February 26, 2026 13:38

Improve data validation

7748bca

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Remove unnecessary null initialized variables

119aded

Remove unused data-bg-original-url attribute

b0e5312

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

westonruter and others added 4 commits February 26, 2026 13:50

Update normalization logic to handle change to attribute order

5331e16

Merge branch 'trunk' of https://github.com/WordPress/performance into…

4c1d7f2

… enhancement/reduce-maximum-image-size-used-as-background-image

westonruter requested changes Feb 26, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Reduce maximum image size used as background image based on container width#2258

Reduce maximum image size used as background image based on container width#2258
nani-samireddy wants to merge 15 commits intoWordPress:trunkfrom
nani-samireddy:enhancement/reduce-maximum-image-size-used-as-background-image

nani-samireddy commented Nov 8, 2025 •

edited

Loading

Uh oh!

codecov bot commented Nov 8, 2025 •

edited

Loading

Uh oh!

github-actions bot commented Nov 8, 2025

Uh oh!

Copilot AI left a comment

Uh oh!

Copilot AI Jan 15, 2026

Uh oh!

Copilot AI Jan 15, 2026

Uh oh!

Copilot AI Jan 15, 2026

Uh oh!

Uh oh!

Uh oh!

westonruter left a comment

Uh oh!

westonruter Feb 26, 2026

Uh oh!

westonruter Feb 26, 2026

Uh oh!

westonruter Feb 26, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

-				// Replace the background image URL in the style attribute.
-				$style = $processor->get_attribute( 'style' );
-				if ( is_string( $style ) ) {
-					$updated_style = str_replace( $background_image_url, $smaller_image_url, $style );
+				// Replace the background image URL in the background/background-image declarations in the style attribute.
+				$style = $processor->get_attribute( 'style' );
+				if ( is_string( $style ) ) {
+					$declarations = explode( ';', $style );
+					foreach ( $declarations as &$declaration ) {
+						$trimmed_declaration = ltrim( $declaration );
+						if (
+=== stripos( $trimmed_declaration, 'background:' ) ||
+=== stripos( $trimmed_declaration, 'background-image:' )
+						) {
+							$declaration = str_replace( $background_image_url, $smaller_image_url, $declaration );
+						}
+					}
+					unset( $declaration );
+					$updated_style = implode( ';', $declarations );

		// Try to get the attachment ID from the data attribute (populated via filter from block attributes).
		$attachment_id = $processor->get_attribute( 'data-bg-attachment-id' );

		add_filter( 'render_block_core/group', 'auto_sizes_add_background_image_data_attributes', 5, 2 );
		add_filter( 'render_block_core/cover', 'auto_sizes_add_background_image_data_attributes', 5, 2 );

Conversation

nani-samireddy commented Nov 8, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Relevant technical choices

Use of AI Tools

Uh oh!

codecov bot commented Nov 8, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

github-actions bot commented Nov 8, 2025

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Copilot AI Jan 15, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jan 15, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jan 15, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

westonruter left a comment

Choose a reason for hiding this comment

Uh oh!

westonruter Feb 26, 2026

Choose a reason for hiding this comment

Uh oh!

westonruter Feb 26, 2026

Choose a reason for hiding this comment

Uh oh!

westonruter Feb 26, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

nani-samireddy commented Nov 8, 2025 •

edited

Loading

codecov bot commented Nov 8, 2025 •

edited

Loading