Block Bindings: Add Cover block support.#74109
Draft
cbravobernal wants to merge 4 commits into
Draft
Conversation
cbravobernal
added
[Type] Enhancement
6 tasks
|
Size Change: +117 B (0%) Total Size: 8.21 MB 📦 View Changed
ℹ️ View Unchanged
|
cbravobernal
force-pushed
the
add/cover-block-bindings-support-v2
branch
3 times, most recently
from
12df79a to
c4ade22
Compare
cbravobernal
force-pushed
the
add/cover-block-bindings-support-v2
branch
from
18b9977 to
f05d8dd
Compare
cbravobernal
force-pushed
the
add/cover-block-bindings-support-v2
branch
from
d16c9ae to
96e8175
Compare
cbravobernal
force-pushed
the
add/cover-block-bindings-support-v2
branch
from
37e917a to
96e8175
Compare
cbravobernal
force-pushed
the
add/cover-block-bindings-support-v2
branch
from
96e8175 to
1a7ceb5
Compare
|
Flaky tests detected in c72ac22. 🔍 Workflow run URL: https://github.com/WordPress/gutenberg/actions/runs/20956197053
|
Contributor
Author
|
I asked Claude for a check of the PR Status. Seems pretty logic. What Was Done (Logical Steps)1. PHP Backend Support ✅
2. Core Binding Detection & Setup ✅
3. Overlay Color Management for Bound Images ✅
4. Pattern Override Support ✅
5. UI Adjustments ✅
6. Documentation ✅ |
Contributor
Author
|
I asked Daniel about hiding the fields from the sidebar if the user cannot edit them here: |
ockham
reviewed
Jan 13, 2026
| */ | ||
|
|
||
|
|
||
| // The following filter can be removed once the minimum required WordPress version is 6.9 or newer. |
Contributor
There was a problem hiding this comment.
Suggested change
| // The following filter can be removed once the minimum required WordPress version is 6.9 or newer. | |
| // The following filter can be removed once the minimum required WordPress version is 7.0 or newer. |
Contributor
|
As discussed on our call yesterday, I think that this PR is quite complex because of its scope; specifically because it contains a few enhancements that aren't directly related to block bindings but required due to lifting some prior constraints of the Cover block. I'd like to address this by breaking the PR down into smaller, defined problems. For example, right now, this PR adds block bindings support for the Cover block's As a result, this PR enhances the Cover block to allow external images. With the aforementioned constraint lifted, the PR has to add substantial code and workarounds in order to make those work. I'd like to avoid this, as I consider it a separate problem. Instead, I'd like to start with a smaller scope, where the Cover block continues to only support internal images. The problems we then need to solve are:
Edit: To experiment with this, let's expose a post's featured image id from the |
7 tasks
This was referenced Jan 22, 2026
ockham
reviewed
Feb 12, 2026
Comment on lines
+243
to
+282
| // Update overlay color when URL comes from a binding source. | ||
| // This handles cases like pattern overrides or custom fields where | ||
| // the URL changes without going through onSelectMedia. | ||
| useEffect( () => { | ||
| if ( hasImageBinding ) { | ||
| updateOverlayFromImage( originalUrl ); | ||
| } | ||
| }, [ originalUrl, hasImageBinding, updateOverlayFromImage ] ); | ||
|
|
||
| useEffect( () => { | ||
| /** | ||
| * If the cover URL is bound (block bindings), disable `useFeaturedImage` | ||
| * and set `dimRatio` to 50. Otherwise, with no media selected, | ||
| * `dimRatio` defaults to 100 and the overlay fully obscures the image. | ||
| */ | ||
| if ( hasImageBinding ) { | ||
| setAttributes( { useFeaturedImage: false } ); | ||
| } | ||
| // Only set dimRatio to 50 once when binding is first detected with dimRatio at 100 | ||
| // This prevents blocking users from manually setting dimRatio to 100 later | ||
| if ( hasImageBinding && dimRatio === 100 && ! dimRatioInitialized ) { | ||
| setAttributes( { dimRatio: 50 } ); | ||
| setDimRatioInitialized( true ); | ||
| } | ||
| // Reset the flag when binding is removed | ||
| if ( ! hasImageBinding ) { | ||
| setDimRatioInitialized( false ); | ||
| } | ||
| // Set backgroundType to image when URL binding provides a URL | ||
| if ( hasImageBinding && originalUrl && ! originalBackgroundType ) { | ||
| setAttributes( { backgroundType: IMAGE_BACKGROUND_TYPE } ); | ||
| } | ||
| }, [ | ||
| originalUrl, | ||
| hasImageBinding, | ||
| dimRatio, | ||
| dimRatioInitialized, | ||
| originalBackgroundType, | ||
| setAttributes, | ||
| ] ); |
Contributor
There was a problem hiding this comment.
After working on #74610 for a while, I realize that this is a pattern that I'd like to avoid as much as possible. The block shouldn't need to care where it gets is attributes from -- i.e. if they're set manually or provided by a Block Binding. Instead, it should be as agnostic as possible.
In the case of the Cover block, this means that all the logic that computes overlay colors, dim ratio, isDark etc. shouldn't live scattered across event handlers (where we rely on those events to happen -- e.g. the user selects a new image from the media gallery to be displayed).
Instead, we should try to move that logic into one shared useEffect handler that will simply react to the url, featuredImage, overlay (and potentially other) attributes changing, and re-compute colors accordingly. This will cover both the case where the user makes a manual change, or the attribute is provided by Block Bindings.
I'm currently trying this out in #74610 (but will probably move to its own PR to keep the changes self-contained). It's a bit finicky, so better e2e coverage should provide us with more confidence: #75483.
Contributor
There was a problem hiding this comment.
Just wanted to mention that this sounds like the same problem as the second item here - Block Fields: Cover block issues.
Contributor
There was a problem hiding this comment.
I also just found out that this would mean we'd go full circle -- after previously moving code from useEffect into event handlers, since useEffect was deemed too fragile 😅 #53253 (comment)
13 tasks
This was referenced May 29, 2026
cbravobernal
force-pushed
the
add/cover-block-bindings-support-v2
branch
from
565e655 to
ef16934
Compare
50 tasks
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What?
Closes #63763.
Adds image block bindings support to the Cover block for
urland optionalid.idandurlas supported bound attributes forcore/cover.<img>, parallax/repeated saved<div>, and Cover markup saved without media.id, when present, to validate attachment media and apply the correctwp-image-{id}class / attachment alt text.core/pattern-overridesworking with Cover image replacement/reset behavior.acf/field, sourlandidbindings to the same image field persist the attachment ID.dimRatio: 100class for bound images and strips auto-derived overlay colors while preserving user-selected overlay colors.Why?
The Cover block is one of the most requested blocks to support block bindings. This improves dynamic layout and pattern workflows, especially for image-driven reusable designs.
Notes
urlis the activation signal.idis optional metadata for internal media.useFeaturedImage.Testing Instructions
Manual
urland, for an attachment image,idto an image source.custom-acf-blocks/acf/fieldsource and confirm changing the Cover image updates the backing image field/meta and the rendered Cover includes the boundwp-image-{id}class.Verified locally
npm run test:unit packages/block-library/src/cover/test/index.js packages/block-library/src/cover/test/edit.js -- --runInBandnpm run lint:js -- packages/block-library/src/cover/index.js packages/block-library/src/cover/edit/index.js packages/block-library/src/cover/edit/inspector-controls.js packages/block-library/src/cover/edit/use-cover-binding-state.js packages/block-library/src/cover/test/index.js packages/block-library/src/cover/test/edit.js test/e2e/specs/editor/blocks/cover.spec.jsvendor/bin/phpcs lib/compat/wordpress-7.1/block-bindings.php phpunit/blocks/render-block-cover-test.phpdocker exec 59a1ff6033218fa39a3dd436c2c0061c-wordpress-1 bash -lc 'cd /var/www/html/wp-content/plugins/gutenberg && vendor/bin/phpunit --filter Tests_Blocks_Render_Cover'env PATH=/Users/carlos/.nvm/versions/node/v20.19.6/bin:/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin npm run buildcustom-acf-blocks:acf/fieldresolved Coverid314and URLhttp://localhost:8889/wp-content/uploads/2026/05/151.png.custom-acf-blockscover_artimage meta field: old write order left meta as0; patched write order left attachment ID314.