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

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 76.08696% with 11 lines in your changes missing coverage. Please review.
✅ Project coverage is 69.26%. Comparing base (c9720dc) to head (f49fdc6).
⚠️ Report is 6 commits behind head on trunk.

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

Additional details and impacted files

@@            Coverage Diff             @@
##            trunk    #2258      +/-   ##
==========================================
+ Coverage   69.21%   69.26%   +0.04%     
==========================================
  Files          90       90              
  Lines        7703     7749      +46     
==========================================
+ Hits         5332     5367      +35     
- Misses       2371     2382      +11

Flag	Coverage Δ
multisite	`69.26% <76.08%> (+0.04%)`	⬆️
single	`35.47% <45.65%> (+0.06%)`	⬆️

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.

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

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

+		$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 );


The data-bg-original-url attribute is set but never read or used anywhere in the image-prioritizer plugin. If this attribute is not needed for the current functionality, consider removing it to reduce HTML bloat. If it's intended for future use or debugging, add a comment explaining its purpose.

Suggested change

$processor->set_attribute( 'data-bg-original-url', $image_url );

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

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

+
+	// Validate extracted data.
+	if (
+		! isset( $attachment_id, $image_url ) ||


While block attributes typically contain integer IDs, consider adding explicit type validation with is_int( $attachment_id ) before line 444 to guard against unexpected data types. This would make the code more defensive and self-documenting about expected input types.

Suggested change

// Validate extracted data.

if (

! isset( $attachment_id, $image_url ) ||

// Normalize attachment ID type if possible.

if ( isset( $attachment_id ) && is_numeric( $attachment_id ) ) {

$attachment_id = (int) $attachment_id;

}

// Validate extracted data.

if (

! isset( $attachment_id, $image_url ) ||

! is_int( $attachment_id ) ||

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

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 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!

Copilot AI Jan 15, 2026

Uh oh!

Copilot AI Jan 15, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 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 );

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

Are you sure you want to change the base?

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

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!

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!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

nani-samireddy commented Nov 8, 2025 •

edited

Loading

codecov bot commented Nov 8, 2025 •

edited

Loading