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

[westonruter]

Feature Description

Consider a Group block that has a background image applied (or a Cover block with a fixed/parallax background): the background image is applied via background-image. This means that there is no srcset to pick the appropriate image, and the full image size is getting used. (The Cover block allows for the resolution to be overridden via the settings panel, but the default is full. The Group block does not provide any resolution setting as far as I can see.)

A Group block with a background image may look like this:

Block Markup

<!-- wp:group {"style":{"background":{"backgroundImage":{"url":"http://localhost:8000/wp-content/uploads/2025/10/American_bison_k5680-1-scaled.jpg","id":536,"source":"file","title":"American_bison_k5680-1"},"backgroundSize":"contain","backgroundRepeat":"no-repeat"},"spacing":{"padding":{"top":"var:preset|spacing|70","bottom":"var:preset|spacing|70","left":"var:preset|spacing|60","right":"var:preset|spacing|60"}},"elements":{"link":{"color":{"text":"var:preset|color|base"}}}},"backgroundColor":"accent-6","textColor":"base","fontSize":"xx-large","layout":{"type":"constrained"}} -->
<div class="wp-block-group has-base-color has-accent-6-background-color has-text-color has-background has-link-color has-xx-large-font-size" style="padding-top:var(--wp--preset--spacing--70);padding-right:var(--wp--preset--spacing--60);padding-bottom:var(--wp--preset--spacing--70);padding-left:var(--wp--preset--spacing--60)"><!-- wp:paragraph {"align":"center","backgroundColor":"accent-6"} -->
<p class="has-text-align-center has-accent-6-background-color has-background"><strong><em>BISON!!!</em></strong></p>
<!-- /wp:paragraph --></div>
<!-- /wp:group -->

Even on Desktop, the image is way too big. The container has a 645px width, and yet the full size being used as the background-image is 2560px wide:

This represents a lot of wasted bytes.

There are two opportunities for us to rectify this in Performance Lab:

1. The Enhanced Responsive Images (auto-sizes) plugin has awareness of the dimensions of blocks on block themes, and it could reduce the size appropriately.
2. With Image Prioritizer (via Optimization Detective), we can know the dimensions of a given element that has the CSS background image added to it (once URL Metrics for Desktop have ben collected). This, in fact, has already been done for the poster of a VIDEO (ref)

We can obtain the various sizes for the background-image and select a smaller one than full for that spot. For example, this is the approprize size:

This example represents a 62% reduction in the file size for the image used as a background image, and this would have big impacts on improving LCP.

Ideally the changes would start here but then migrate into Gutenberg for core merge soon after, especially in the case of the Enhanced Responsive Images patch.

See also:

• Background image block support: optimize image output gutenberg#59113

[nani-samireddy]

Hi @westonruter 👋,

I tested this behaviour locally by adding a background image to a group block, and it is indeed returning the maximum resolution of that image, as you mentioned.

I followed the reference you provided for the video poster, and I also agree that it's the best approach.

I've implemented the following function, which can be called just before this line.

Let me know what you think!

/**
    * Reduces background image size by choosing one that fits the element dimensions more closely.
    *
    * This is similar to how VIDEO poster images are optimized in the Video Tag Visitor.
    *
    * @since 0.4.0
    *
    * @param non-empty-string       $background_image_url Background image URL.
    * @param OD_Tag_Visitor_Context $context              Tag visitor context, with the cursor currently at an element with a background image.
    */
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 URL.
    $attachment_id = attachment_url_to_postid( $background_image_url );

    if ( $attachment_id > 0 ) {
        $smaller_image_url = wp_get_attachment_image_url( $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 );
            }
        }
    }
}

[westonruter]

@nani-samireddy Thanks for this. I think we might be able to get away with not using attachment_url_to_postid(). The reason is that the block markup includes the image attachment ID among the block attributes (as id). I think it would be ideal if we added a filter which exposed that underlying ID as data attribute on the element which we could then reuse later in a tag visitor callback function like you have here.

I don't believe what you have here will always work because, for example, the Cover block actually allows you to pick a smaller image size than full, in which case the attachment_url_to_postid() function will fail to locate the attachment (as I understand). The Video poster had to resort to using attachment_url_to_postid() because the block attributes do not store the attachment ID, unfortunately. So if someone picks the "large" resolution for the Cover block, and yet this is still too large for the Cover block, then we should be able to downsize it further to a medium resolution.

[nani-samireddy]

@westonruter Thanks for the reply. I’ll make the changes you mentioned and raise a PR.

Also, the Cover block uses an img tag for the background image, which should already be optimized by the auto_sizes_filter_image_tag function. Since we're currently discussing blocks that use inline CSS for background images, I believe this wouldn't apply to the Cover block—correct?

Please let me know if I’m missing anything.

[westonruter]

@nani-samireddy The Cover block does use an IMG by default, but it uses a background image when you select the "fixed background" setting:

[nani-samireddy]

@westonruter Sorry for the delay, I raised this PR with the above changes #2258