Skip to content

Fix: Cover block image sizes#78562

Open
DarkMatter-999 wants to merge 3 commits into
WordPress:trunkfrom
DarkMatter-999:fix/cover-block-image-sizes
Open

Fix: Cover block image sizes#78562
DarkMatter-999 wants to merge 3 commits into
WordPress:trunkfrom
DarkMatter-999:fix/cover-block-image-sizes

Conversation

@DarkMatter-999
Copy link
Copy Markdown
Contributor

What?

Closes #77387

This PR dynamically calculates and overwrites the sizes attribute for Cover block background images based on the block's min-height and the image's aspect ratio. It ensures that when object-fit: cover forces an image to scale up vertically, the browser requests an image size adequate for the rendered height rather than defaulting to a narrow rendered width.

Why?

When standard or auto sizes are applied to a lazy-loaded image inside a Cover block, browsers use the layout width of the image element to determine which srcset image source to download.

However, because the Cover block uses object-fit: cover and often enforces a rigid min-height, a narrow Cover block container (e.g., inside a column) will clip the sides of a wide image to fulfill that height requirement. This means the layout width is small, but the image is actually scaled up significantly to match the height. The browser mistakenly downloads a low-resolution thumbnail, resulting in highly pixelated, blurry background images on both desktop layouts and mobile viewports.

How?

In the PHP render callback for the Cover block, we intercept the image rendering logic (for both standard uploaded background images and Featured Images), there we calculate the aspect ratio of the image and dynamically set the sizes for the images.

This is an initial proof of concept to align on the architectural approach. Once the reviewers confirm this implementation path is correct, I will follow up by adding the corresponding tests as needed.

Testing Instructions

  1. Create a post or page with enough content/blocks so that blocks lower on the page will trigger lazy loading.
  2. Insert a Columns block to create a narrow layout column.
  3. Inside one of the narrow columns, insert a Cover block.
  4. Set the Cover block's Minimum Height to 600px.
  5. Upload or select a wide, short image (e.g., an image with a 2400x600 or 1600x400 landscape resolution).
  6. Save and view the page on the frontend (ensure the Cover block requires scrolling to be lazy-loaded).
  7. Inspect the image markup via DevTools. Verify that the sizes attribute contains the newly calculated dynamic fallback (e.g., (max-width: 2400px) 2400px, 100vw) instead of a basic width or only auto.
  8. Confirm that the image renders crisp and sharp, pulling a high-resolution source from the srcset rather than a pixelated smaller file.

Screenshots or screencast

Before

cover-block-image-sizes.mov

After

cover-block-image-sizes-fix.mov

Use of AI Tools

I used Gemini 3.5 Flash to draft and format this Pull Request description based on the codebase changes provided.

@github-actions github-actions Bot added the [Package] Block library /packages/block-library label May 22, 2026
@DarkMatter-999 DarkMatter-999 marked this pull request as ready for review May 22, 2026 11:42
@github-actions
Copy link
Copy Markdown

Warning: Type of PR label mismatch

To merge this PR, it requires exactly 1 label indicating the type of PR. Other labels are optional and not being checked here.

  • Required label: Any label starting with [Type].
  • Labels found: [Package] Block library.

Read more about Type labels in Gutenberg. Don't worry if you don't have the required permissions to add labels; the PR reviewer should be able to help with the task.

@github-actions
Copy link
Copy Markdown

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: DarkMatter-999 <lakshyajeet@git.wordpress.org>
Co-authored-by: adithya-naik <adithyanaik@git.wordpress.org>
Co-authored-by: eric-michel <ytfeldrawkcab@git.wordpress.org>

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

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

[Package] Block library /packages/block-library

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Auto sizes in cover block can easily cause poor image selection

1 participant