Make WordPress Core

Opened 7 weeks ago

Last modified 7 weeks ago

#64725 new enhancement

Background block support: render uploaded images as <img> for responsive image support

Reported by: josvelasco's profile JosVelasco Owned by:
Milestone: Awaiting Review Priority: normal
Severity: normal Version: trunk
Component: Editor Keywords: has-patch has-unit-tests needs-testing
Focuses: javascript, css, tests, performance Cc:

Description

For blocks using the background block support (e.g. Group), uploaded background images sized Cover or Contain with no tiling are now rendered as a native <img> element instead of CSS background-image.

This gives browsers access to srcset/sizes for responsive image selection, loading="lazy" for deferred loading, and decoding="async" for non-blocking decode benefits that CSS background-image cannot provide.

'no-repeat' is treated the same as unset (both compatible with object-fit). Only explicit tiling values (repeat, repeat-x, repeat-y) and background-attachment:fixed keep the CSS path.

The block wrapper receives position:relative to contain the absolutely-positioned <img>.
A guard prevents stomping any existing position: rule already on the wrapper.

Gutenberg PR

https://github.com/WordPress/gutenberg/pull/75885

Core PR

https://github.com/WordPress/wordpress-develop/pull/11050

Change History (1)

This ticket was mentioned in PR #11050 on WordPress/wordpress-develop by @JosVelasco.


7 weeks ago
#1

## Description

For Group blocks (and any block using the background block support) with an uploaded background image sized Cover or Contain and no tiling repeat, wp_render_background_support() now injects a native <img> element as the first child of the block wrapper instead of using CSS background-image.

This gives browsers access to:

  • srcset / sizes for responsive image selection
  • loading="lazy" — deferred loading for below-fold images
  • decoding="async" — non-blocking image decode
  • The browser's native image cache (shared with other <img> references to the same attachment)

'no-repeat' is treated identically to unset — both are compatible with object-fit. Only explicit tiling values (repeat, repeat-x, repeat-y) require CSS background-image. background-attachment: fixed (parallax) also stays on the CSS path since it has no <img> equivalent.

The wrapper receives position: relative to contain the absolutely-positioned <img>. A guard prevents stomping any existing position: rule already on the wrapper.

## Changes

  • src/wp-includes/block-supports/background.php: Added $use_img_element check and <img> injection before the CSS fallback path. Added @since 6.8.0 docblock entry.
  • tests/phpunit/tests/block-supports/wpRenderBackgroundSupport.php: Added two data provider cases (tiling repeat and fixed attachment fall back to CSS) and two standalone test methods (cover and contain+no-repeat inject <img>).

## Trac ticket

https://core.trac.wordpress.org/ticket/64725

## Gutenberg PR

https://github.com/WordPress/gutenberg/pull/75885

## Testing

Run the updated test class:

phpunit --filter Tests_Block_Supports_WpRenderBackgroundSupport

---

🤖 This PR was prepared as a core backport for WordPress/gutenberg#75885. All code was human-reviewed before submission.

Note: See TracTickets for help on using tickets.