![(please configure the [header_logo] section in trac.ini)](/chrome/site/your_project_logo.png){kind=logo}
Opened 5 months ago
Last modified 8 weeks ago
#64725 new enhancement
Background block support: render uploaded images as <img> for responsive image support
| Reported by: | JosVelasco | Owned by: | |
|---|---|---|---|
| Priority: | normal | Milestone: | Awaiting Review |
| Component: | Editor | Version: | |
| Severity: | normal | Keywords: | has-patch |
| Cc: | Focuses: | javascript, css, tests, performance |
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
Attachments (1)
Change History (5)
This ticket was mentioned in PR #11050 on WordPress/wordpress-develop by @JosVelasco.
5 months ago
#1
#2
@
2 months ago
- Keywords has-unit-tests needs-testing removed
Tested this patch on WordPress Beta 7 and verified that the implementation behaves as expected and aligns with the requirements outlined in the ticket.
Tested scenarios
Group block with background image using cover and no-repeat
Group block with background image using contain and no-repeat
Background images with background-attachment: fixed
Results
Confirmed that background images using cover or contain without tiling are now rendered using a native <img> element instead of a CSS background-image.
Verified that the rendered <img> includes responsive and performance-related attributes such as srcset, sizes, loading="lazy", and decoding="async".
Confirmed that no-repeat is treated equivalently to an unset repeat value.
Verified that explicit tiling values and background-attachment: fixed correctly continue using the CSS background-image rendering path.
Confirmed that position: relative is applied to the wrapper only when necessary and does not override any existing position styles.
## 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 CSSbackground-image.This gives browsers access to:
srcset/sizesfor responsive image selectionloading="lazy"— deferred loading for below-fold imagesdecoding="async"— non-blocking image decode<img>references to the same attachment)'no-repeat'is treated identically to unset — both are compatible withobject-fit. Only explicit tiling values (repeat,repeat-x,repeat-y) require CSSbackground-image.background-attachment: fixed(parallax) also stays on the CSS path since it has no<img>equivalent.The wrapper receives
position: relativeto contain the absolutely-positioned<img>. A guard prevents stomping any existingposition:rule already on the wrapper.## Changes
src/wp-includes/block-supports/background.php: Added$use_img_elementcheck and<img>injection before the CSS fallback path. Added@since 6.8.0docblock 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:
---
🤖 This PR was prepared as a core backport for WordPress/gutenberg#75885. All code was human-reviewed before submission.