Image: Include the Add toolbar button from the Gallery block when nested within a Gallery

[andrewserong]

What?

Fixes #47200

Share and "Add" toolbar button between the Gallery block and Image blocks that are nested within a Gallery block. That is, expose the gallery block's Add control to the child image block.

Why?

As described in #47200 it can be hard to find where to add images to a gallery block just by selecting the gallery block as a first click onto an image within the gallery.

So, this PR tries a fairly naive approach of sharing the control between the image and gallery blocks. It intentionally doesn't use the "__experimentalExposeControlsToChildren" support because:

• We only want to share the "Add" control
• And we want the "Add" control to line up right next to the Replace control so that things feel consistent

There's discussion elsewhere e.g. in #61209 (comment) for other options of exposing parent/child controls, but IMO I think Gallery -> Image might be kind of unique in this respect as it's just about exposing "Add" for now. That said, open to ideas here!

How?

• Turn the Gallery block's "Add" button into a shared AddImagesToolbarControl component
• In the Image block, inject the AddImagesToolbarControl right next to the Replace control when the image is a child of a Gallery block

Testing Instructions

• Add a Gallery block to a post or page
• Give it at least a single image
• Click the image within the Gallery block and see that there is now an "Add" button alongside the "Replace" button
• Check that clicking "Add" behaves just as it does on the Gallery block itself (allows you to add images to the gallery)
• Smoke-test that an image not in a Gallery block doesn't show the Add button, and that a wrapper Gallery block does show the Add button

Screenshots or screencast

A quick video showing "Add" working at both the Image and Gallery block levels:

2026-08-12.15.55.27.mp4

Use of AI Tools

Claude Code Opus 5 to develop the change, and I've been reviewing and testing as I go

[github-actions]

Size Change: +234 B (0%)

Total Size: 7.71 MB

📦 View Changed

Filename	Size	Change
build/scripts/block-library/index.min.js	357 kB	+234 B (+0.07%)

_{compressed-size-action}

[github-actions]

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.

Unlinked Accounts

The following contributors have not linked their GitHub and WordPress.org accounts: @aisajib, @mikeicode.

Contributors, please read how to link your accounts to ensure your work is properly credited in WordPress releases.

If you're merging code through a pull request on GitHub, copy and paste the following into the bottom of the merge commit message.

Unlinked contributors: aisajib, mikeicode.

Co-authored-by: andrewserong <andrewserong@git.wordpress.org>
Co-authored-by: jasmussen <joen@git.wordpress.org>
Co-authored-by: fcoveram <fcoveram@git.wordpress.org>
Co-authored-by: richtabor <richtabor@git.wordpress.org>
Co-authored-by: hanneslsm <hanneslsm@git.wordpress.org>
Co-authored-by: danielbachhuber <danielbachhuber@git.wordpress.org>

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

[jasmussen]

Nice. Pretty simple:

Not a problem with this PR, but I do worry for people that use "text labels only", the toolbar is now so wide it only JUST fits before the mobile breakpoint:

I think we might have added horisontal scrolling to the block toolbar, but I don't recall? In any case, a block toolbar refactor seems worth looking at in the near future.

Functionally, I'm okay with it, but would appreciate a gut check by @WordPress/gutenberg-design. The larger piece is that there's a lot of code changed, I'll defer to you and other devs to make sure that's valid and good.

Thanks for looking at it!

[andrewserong]

Thanks for taking a look @jasmussen! Let's see what others think, too.

The larger piece is that there's a lot of code changed, I'll defer to you and other devs to make sure that's valid and good.

I should have mentioned in the PR description, this looks like a bigger code change than it is. Most of the code remains the same, just moved into a shared hook and component (so it can be shared with the Image block), but it should otherwise be functionally identical. I think this makes things a little neater for the Gallery block.

[fcoveram]

I haven't run the PR because the video attached shows it clearly. The change is simple and adds value, so thumbs up to the change.

Regarding the toolbar, I agree with Joen about the refactor. We have talked in other tickets about the needs and opportunities the toolbar has.