Block setup states: Include both inspector and toolbar options for setting and resetting

Consider the Site Logo block in its setup state:

This selected Site Logo block shows:

"Choose logo" in the block toolbar
"Choose logo" as a matching button in the inspector

When a media file is added, both of those are updated:

In this case, the selected Site Logo block shows:

"Replace" in the block toolbar
The filename of the image, plus a thumbnail, in the media button in the inspector.

Beyond the basic usability, this also has benefits as far as scaling down to tiny sizes in complex patterns. See #64288.

The pattern from Site Logo would be good to make consistent across all similar blocks. In most cases, this would mean adding a panel to the inspector, "Media".

Image

Missing "Media" section.

Media & Text

Missing "Media" section, and block toolbar option.

Cover

Missing "Media" section initially, it's there when an image has already been set. Also, it should be "Add media", not "Add Media".

Query Loop

Directly related to enhancements outlined in #64288, it's missing the toolbar option, as well as a section in the inspector. Since this is about swapping out patterns, rather than adding media, the pattern could potentially be the collapsed "Design" section, that's similar for when you choose page-level patterns in the document status inspector.

@annezazu

Curious your thoughts, @annezazu!

Absolutely love this and think this would help immensely for consistency, especially when we think about "write" mode. For example, I think having a 'design' section for the query loop would be a great thing to display in a contentOnly representation #66614.

@jasmussen

Thank you @jasmussen for reporting this issue.

I'd like to work on this issue and have a draft PR ready soon .

@Mamaduka

This issue has had a good amount of attention recently, so I ran a larger audit of where every media block stands today.

The four blocks named in the description are now consistent, but the same inconsistency turns out to run wider than those four. Two shortfalls recur across the rest:

No Media section in the sidebar. Media can only be set from the toolbar or the placeholder, so the sidebar offers nothing for it.
No option in the toolbar until media already exists. The block shows its placeholder with an empty toolbar, and only once media is added does a "Replace" option appear. So the toolbar offers replacing but never adding, the same gap that was addressed for Media & Text in feat: Introduce 'Add Media' in the block controls for media-text block #82420.

Here is where each block stands:

Block	Media section in sidebar	Toolbar option before media is added
Site Logo	✅ Existed in trunk	✅ Existed in trunk
Image	✅ Existed in trunk	✅ Existed in trunk
Media & Text	✅ #82593	✅ #82420
Cover	✅ #82751	✅ Existed in trunk
Video	🚧 #84602	🚧 #84602
Audio	🚧 #84605	🚧 #84605
File	🚧 #84608	🚧 #84608
Playlist Track	❌	❌
Post Featured Image	❌	❌

The first four are the pattern this issue describes, and they behave consistently after the recent work in #82389, #82420, #82593 and #82751. Every block below them still shows the placeholder-only empty state.

Happy to take these on in small batches, starting with Video and Audio since they behave almost identically. What are your thoughts on this?

cc: @Mamaduka @talldan @jasmussen

Hi Team,

Just a soft nudge here, I’d appreciate your thoughts on this #66563 (comment)

Since we’ve standardised four media-related blocks, do you think we should extend the same pattern in small batches to some of the other blocks listed in the table?

I think Video, Audio, and File are relatively low-risk candidates to start with.

Thanks for the (re)ping, been busy days!

For me the question is technically simple: every block that can set media should have the same systematic interface. And presumably all such blocks already have a "Replace" option in the block toolbar. Therefore, emphatic yes: all such blocks should have a toolbar option in their setup states, and a "Media" panel in the settings panel of the block inspector. The more generic and systematic the code reusage can be, the better, e.g. "Typography" is simply a block supports panel, honesly the "Media" panel should be as-simple if possible. There's no reason to have 10 different implementations of the same Media panel if we can have one.

The only nuance, please keep pinging @WordPress/gutenberg-design on any PRs for a quick visual gut-check. While I'm fairly sure the above holds for all the blocks mentioned, there could be nuance worth just a quick glance in implementation.

Thanks for contributing!

While reviewing several PRs, I noticed that the media control in the inspector (MediaControl) always reserves space for a thumbnail image. This means that for blocks that never have an image preview, such as the Video and Audio blocks, nothing is ever rendered in that area.

Do we need some kind of option to improve this?

This means that for blocks that never have an image preview, such as the Video and Audio blocks, nothing is ever rendered in that area.

Do we need some kind of option to improve this?

Yes, an icon based on the media type seems like the natural fix. Cover has the same gap with video backgrounds, so it'd cover that too.

Happy to put up a PR.

I can see both sides. My feeling is that one predictable place across every media block is worth the click, the sidebar is persistent and findable, where the toolbar needs you to know it's there. But that's a preference rather than something the toolbar can't do, so happy to follow whatever you all land on.

It's a valid point, but I don't agree with it. I think there are options for simplifying the media inspector control that we can look at, including where it lives. But as is:

It's already in place in a number of blocks
It doesn't take up that much space
It solves a real problem where blocks in a really narrow constrained context where their placeholder is just grey, the way to add media is still discoverable

So I'd like to unblock this and either embrace the decision to have this media button across all media blocks, or actively remove it from all media blocks so at least it's consistent. Consider here Site Logo, where the media button feels extra useful IMO to have.

Jay if you have time to chime in, I'd love your thoughts on where we might go. Is there a third option I'm forgetting?

There are trade-offs both ways, so no strong feelings from me. This does however raise a higher-level question about how we decide whether a tool is toolbar only, toolbar + inspector, or inspector only. A documented source of truth will help when this kind of question surfaces again in the future, and for authors/agents building new blocks.

A documented source of truth will help when this kind of question surfaces again in the future, and for authors/agents building new blocks.

💯, I'll work on that.

In this case for me it's about setup states, along the lines of "if the tool is critical from moving a block from its setup state, which can be tiny and compact, to a functional block, then it belongs in both inspector and toolbar". Does that resonate? If yes, I'll work on those docs.

Noting just after writing the above, some concern is elaborated upon here, so I'll pause the suggestion above for now.

I followed the comments shared in #84602 (Video), #84605 (Audio) and #84608 (File), and here is a simple idea for the different types and states of the control in the Inspector.

The slot left of the label is always present. What's inside depends on the file type.

The control interactions remain the same.
Eventually, video could show the cover frame as an image thumbnail.
The "file" icon is a folder and could be a different element. But that's not part of this ticket scope.

Those are the media upload buttons in the inspector, yes? If so, I dig them!

@jasmussen

Yes @jasmussen. Sorry for missing that point

@fcoveram

@fcoveram curious if you tried a version with a + icon for the placeholder state. For audio, video, and file there's not much difference between the placeholder and filled states, maybe a different icon would help.

if the tool is critical from moving a block from its setup state, which can be tiny and compact, to a functional block, then it belongs in both inspector and toolbar

Sounds reasonable, but there might be some nuance. By this logic shouldn't a paragraph block have a Content field in the Inspector?

By this logic shouldn't a paragraph block have a Content field in the Inspector?

No because an empty paragraph can be valid, e.g. two linebreaks.

But we can narrow it to something like:

if the tool is critical from moving a block from its Placeholder state, which can be tiny and compact, to a functional block, then it belongs in both inspector and toolbar

Is that fair? That would narrow it to the grey blob material.

curious if you tried a version with a + icon for the placeholder state. For audio, video, and file there's not much difference between the placeholder and filled states, maybe a different icon would help.

I like the idea. Here is an updated version

I think that makes it a little easier to identify set/unset states at a glance.

One other question, can users drag media into these controls to upload/replace? If so they should probably have dashed outlines like the featured image control:

In fact there could be an argument to include the featured image control in this work since it's handling the same workflow.

If so they should probably have dashed outlines like the featured image control

Same material yes, makes sense. I'm not super convinced about the dashed line at the moment, it feels "sharp" for lack of a better word. It could just be adjusting carefully the dash-pattern or making the gap smaller. But one thing: does the dashed line have to be brand coloured? Dropzones for me feel neutral, even if they are also interactive (tappable).

Yes I think making it neutral makes sense.

I don't think there's any way to adjust the dash properties with css, but we could maybe do something like this: https://kovart.github.io/dashed-border-generator/?

One other question, can users drag media into these controls to upload/replace? If so they should probably have dashed outlines like the featured image control:

I'm also not convinced about the dashed line. I think I've only seen it for that control. Using the styles from WPDS primitives, such as Select, sounds more logic to me.

In fact there could be an argument to include the featured image control in this work since it's handling the same workflow.

You mean adding the field in the Inspector > "Content" tab? Not sure I'm following you.

Navigation Menu

Repository navigation

Block setup states: Include both inspector and toolbar options for setting and resetting #66563

1 remaining item

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Block setup states: Include both inspector and toolbar options for setting and resetting #66563

Description

Activity

jasmussen commented on Nov 1, 2024

annezazu commented on Nov 1, 2024

im3dabasia commented on Jan 8, 2025

im3dabasia commented on Sep 23, 2026

im3dabasia commented on Oct 8, 2026

jasmussen commented on Oct 8, 2026

t-hamano commented on Oct 13, 2026

1 remaining item

im3dabasia commented on Oct 14, 2026

jasmussen commented on Oct 19, 2026

jameskoster commented on Oct 20, 2026

jasmussen commented on Oct 20, 2026

jasmussen commented on Oct 20, 2026

fcoveram commented on Oct 20, 2026

jasmussen commented on Oct 20, 2026

fcoveram commented on Oct 20, 2026

jameskoster commented on Oct 20, 2026

jasmussen commented on Oct 20, 2026

fcoveram commented on Oct 21, 2026

jameskoster commented on Oct 22, 2026

jasmussen commented on Oct 22, 2026

jameskoster commented on Oct 22, 2026

fcoveram commented on Oct 22, 2026

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions