Package blocks: Introduce a utility for getting the block image#68910
Merged
fabiankaegy merged 7 commits intotrunkfrom Jul 10, 2025
Merged
Package blocks: Introduce a utility for getting the block image#68910fabiankaegy merged 7 commits intotrunkfrom
fabiankaegy merged 7 commits intotrunkfrom
Conversation
Add a utility function to the Blocks API that gets an image URL. Blocks can register a __experimentalImage setting to pass any chosen image URL depending on context. A context may be for example the list-view.
carolinan
added
[Feature] List View
|
Size Change: +139 B (+0.01%) Total Size: 1.89 MB
ℹ️ View Unchanged
|
|
Flaky tests detected in 0fc2437. 🔍 Workflow run URL: https://github.com/WordPress/gutenberg/actions/runs/14187136856
|
carolinan
commented
Mar 3, 2025
| block.attributes?.mediaAlt || | ||
| '', | ||
| clientId: block.clientId, | ||
| }, |
Contributor
Author
There was a problem hiding this comment.
The alt is not currently used. I included it to match getImage. Perhaps it can be useful in the future.
carolinan
requested review from
ajitbohra,
ellatrix and
fabiankaegy
as code owners
|
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 If you're merging code through a pull request on GitHub, copy and paste the following into the bottom of the merge commit message. To understand the WordPress project's expectations around crediting contributors, please review the Contributor Attribution page in the Core Handbook. |
Contributor
Author
|
Do I need to add a manual changelog entry for an experimental feature? |
carolinan
removed
the
[Priority] Low
fabiankaegy
approved these changes
Jul 10, 2025
Member
fabiankaegy
left a comment
fabiankaegy
left a comment
There was a problem hiding this comment.
Love this PR! This is going to be a very useful feature for custom block development also :)
To me the code also looks good and the feature tests well!
fabiankaegy
added
the
props-bot
github-actions
bot
removed
the
props-bot
Member
|
@carolinan do we want to refactor the Image Block etc to use the new API in a follow up now? :) |
Mamaduka
reviewed
Jul 10, 2025
Member
Mamaduka
left a comment
Mamaduka
left a comment
There was a problem hiding this comment.
do we want to refactor the Image Block etc to use the new API in a follow up now? :)
I think that would be a good idea.
| __experimentalSanitizeBlockAttributes, | ||
| getBlockAttributesNamesByRole, | ||
| __experimentalGetBlockAttributesNamesByRole, | ||
| getBlockImage as __experimentalGetBlockImage, |
Member
There was a problem hiding this comment.
I believe this should be a private API. The project should no longer expose experimental or unstable APIs to the public.
| }, | ||
| ], | ||
| }, | ||
| __experimentalImage( attributes, { context } ) { |
Member
There was a problem hiding this comment.
Side note: The property name will be generic when/if it's stabilized.
Contributor
Author
I do not have the availability. |
Member
All good :) Thanks for the heads up 👍 |
t-hamano
reviewed
Jul 11, 2025
Contributor
t-hamano
left a comment
t-hamano
left a comment
There was a problem hiding this comment.
Sorry for the late review.
I have three concerns:
First, not only the getBlockImage selector but also the __experimentalImage field is made public. In my understanding, this means that the API specifications cannot be easily changed in the future and the field with the __experimental prefix should be supported forever.
For example, how about only allowing this field in certain core blocks like below? This way we can safely make changes to the API in the future and release it when we're ready.
export default function useListViewImages( { clientId, isExpanded } ) {
// ...
const images = useMemo( () => {
if ( ! IMAGE_SUPPORTED_BLOCKS.includes( block.name ) ) {
return getImagesFromBlock( block, isExpanded );
}
// ...
}, [ block, isExpanded ] );
return images;
}The second concern is the lack of support for multiple images. I think this API should be adapted to the Gallery block as well.
Third, do we really need the __experimentalGetBlockImage selector? We can probably define the same functionality as an internal function in this file.
If we need to address these tasks, I'd be happy to help.
Member
|
@t-hamano, I also share your concerns and have some ideas how to get this working only for core blocks at the moment. Do you mind creating an issue for follow-ups, assign it to me and I’ll create PoC PR. |
Contributor
This was referenced Jul 14, 2025
cbravobernal
pushed a commit
that referenced
this pull request
Jul 15, 2025
…URL's to be used in places like the list view (#68910) Add a utility function to the Blocks API that gets an image URL. Blocks can register a __experimentalImage setting to pass any chosen image URL depending on context. A context may be for example the list-view. Co-authored-by: carolinan <poena@git.wordpress.org> Co-authored-by: fabiankaegy <fabiankaegy@git.wordpress.org> Co-authored-by: andrewserong <andrewserong@git.wordpress.org> Co-authored-by: mtias <matveb@git.wordpress.org> Co-authored-by: colorful-tones <colorful-tones@git.wordpress.org> Co-authored-by: richtabor <richtabor@git.wordpress.org>
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
4 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?
Add a basic utility function to the Blocks API that gets a custom image URL from a block.
Blocks can register a
__experimentalImagesetting to pass any chosen image URL depending on context. A context may be for example thelist-view.For #53684
What the PR does not do:
It does not update the code that displays the preview image from the image or gallery blocks in the List View,
Why?
The List View shows a small preview of the image used in image block and gallery.
But it is hardcoded to the
urlattribute of the image block.Instead of hardcoding it, an API can be used. Such an API can be used to present the image in other parts of the interface if the need and want should occur, and not be limited to the list view.
See #53381 (comment)
The implementation is similar to that of
__experimentalLabelThe reason why this utility is helpful is because the block can use any
urlas the image source. Different blocks may name the source url for their images differently. For example, in the Media & Text block, the attribute is called "mediaUrl"Or, the block may want to use a specific custom image that is not a block attribute.
How?
The pull request updates the Media & Text block and the Cover block to include a new setting called
__experimentalImage.This setting uses the block attributes and the context, and conditionally returns the url of the image.
The pull request adds a function named
getBlockImageto the utility file of the blocks API.It collects
__experimentalImagefrom the block type and conditionally returns the url.The API exports the function as
__experimentalGetBlockImage.Finally,
__experimentalGetBlockImageis imported in the List View, inuseListViewImages,and is used to determine the url of the miniature image to show in the List View.
Testing Instructions
Insert and add images to:
An image block
A cover block
A media & text block
Open the List View. Confirm if the mentioned blocks have image previews.
Screen readers
The image is a background in a span that has
aria-hidden="true", this is unchanged and it does not need testing with a screen reader.Screenshots or screencast