Editor: Refactor the Options menu to use the Menu component

[Mamaduka]

What?

Builds on #79560.
PR also contains #81507. Can be shipped separately.

PR migrates the editor's Options menu from DropdownMenu to Menu from @wordpress/ui.

How?

@wordpress/ui is bundled into each package instead of being shared as a script, so each package gets its own copy of Menu and its own React context. A component in edit-post cannot render a menu part into the menu the editor renders: the context it looks for belongs to a different copy, and the item throws. Every item in this menu therefore has to be rendered by a component that comes from the editor.

There are three kinds of items, and each gets there differently:

• Items in edit-post and edit-site, which fill the private slots of the menu. The editor exposes MoreMenuItem and MoreMenuPreferenceItem as private APIs, and those fills render them.
• Items of the plugins API. ActionItem now takes the component to render from the as the slot passes through fillProps, so the menu hands its own item component to every fill. Plugin authors keep using PluginMoreMenuItem and PluginSidebarMoreMenuItem as before.
• Items that pass an as of their own. Those keep rendering their component, wrapped so that they still take part in keyboard navigation.

Notes

• Need to decide if we should log a warning for slots using a non-compatible as prop.
• Popovers opening from a new Menu don't properly return focus on close.
• Should we introduce a shared helper for keyboard shortcut representations in @wordpress/keycodes and @wordpress/keyboard-shortcuts, which would replace the local helper in the editor.

Testing Instructions

1. Smoke test the main Options menu in the post and site editors. They should function as before.
2. Test menu items from plugins - test/e2e/specs/editor/plugins/plugins-api.spec.js covers most of the cases.
3. Test Notes menu, which is implemented as a plugin sidebar.

Testing Instructions for Keyboard

Same.

Screenshots or screencast

CleanShot.2026-08-13.at.11.06.19.mp4

Use of AI Tools

Assisted by Claude.

[github-actions]

Size Change: +898 B (+0.01%)

Total Size: 7.92 MB

📦 View Changed

Filename	Size	Change
build/scripts/edit-post/index.min.js	52.7 kB	+28 B (+0.05%)
build/scripts/edit-site/index.min.js	383 kB	+20 B (+0.01%)
build/scripts/edit-widgets/index.min.js	22.5 kB	-3 B (-0.01%)
build/scripts/editor/index.min.js	582 kB	+711 B (+0.12%)
build/styles/editor/style-rtl.css	31.6 kB	+46 B (+0.15%)
build/styles/editor/style-rtl.min.css	27.1 kB	+29 B (+0.11%)
build/styles/editor/style.css	31.7 kB	+38 B (+0.12%)
build/styles/editor/style.min.css	27.1 kB	+29 B (+0.11%)

_{compressed-size-action}

[jasmussen]

Oh yes! Fantastic, this is a substantial improvement.

Noting that I'm seeing a few small issues:

Also, I expect that these two options should be radio options with dots, though I'm aware that @ciampo is currently working on some details there so they may not be radios in the first couple of iterations:

Thanks for this. I assume this allows us to make submenu flyouts too? Doesn't have to be in this PR, but there are a couple of things I'd like to rearrange in order to add room for a future "Suggesting" mode group.

[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.

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: Mamaduka <mamaduka@git.wordpress.org>
Co-authored-by: ciampo <mciampini@git.wordpress.org>
Co-authored-by: jasmussen <joen@git.wordpress.org>
Co-authored-by: aduth <aduth@git.wordpress.org>

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

[Mamaduka]

The icon position bug is on the main branch - #79560 (comment). I'll swap radio/checkboxes when there's a final decision; it's not a problem.

I assume this allows us to make submenu flyouts too? Doesn't have to be in this PR, but there are a couple of things I'd like to rearrange in order to add room for a future "Suggesting" mode group.

Yes, I think both Notes and Suggesting want to use flyouts. Let me know what you would like to see rearranged. We could experiment and also push a demo for flyouts.

We can always revert/extract things that don't have to be part of this PR, but would be good for testing.

[jasmussen]

Actually I was thinking something like this:

But the "Appearance" part assumes that things like top toolbar and such move into preferences as part of @youknowriad's #74546. If that doesn't land we can just show checkboxes like we have today.

[jasmussen]

Still pretty long, and we can move some of the other groups into flyouts too, if need be—assuming it's not hard to do.

[Mamaduka]

Just pushed the Help submenu example with small differences compared to the mockup:

• No icon; we can add it once the bug is fixed on the main branch.
• Welcome Guide remains in the More Actions section. It's using the same slot as "Manage Patterns", so it's not easy to separate.

Screenshot

[jasmussen]

Nice, good to know that it's easy. If we can't move the Welcome Guide (interesting about the slot), I don't think we should add a help flyout.

Let's not do the following now so as to not distract the PR overall, keep it focused at simple), but we could create a menu item called "More actions" where documentation, keyboard shortcuts, copy all blocks, manage patterns, and welcome guide all live. It needs a bit more thought, but it's an option.

[Mamaduka]

Reverted for now. We can return to submenu re-organization later.

[github-actions]

Flaky tests detected in 056f45e.
Some tests passed with failed attempts. The failures may not be related to this commit but are still reported for visibility. See the documentation for more information.

🔍 Workflow run URL: https://github.com/WordPress/gutenberg/actions/runs/33427440884
📝 Reported tests:

Should navigate inner blocks with arrow keys in /test/e2e/specs/editor/various/writing-flow.spec.js, passed after 1 failed attempt.

TimeoutError: locator.click: Timeout 10000ms exceeded.
Call log:
  - waiting for getByRole('listbox', { name: 'Blocks' }).getByRole('option', { name: 'Paragraph' })

    at WritingFlowUtils.addDemoContent (/home/runner/work/gutenberg/gutenberg/test/e2e/specs/editor/various/writing-flow.spec.js:1482:5)
    at /home/runner/work/gutenberg/gutenberg/test/e2e/specs/editor/various/writing-flow.spec.js:30:3

[ciampo]

• Need to decide if we should log a warning for slots using a non-compatible as prop.

Happy to discuss more in details

• Popovers opening from a new Menu don't properly return focus on close.

This should be hopefully fixed in #79560 (together with the icon layout)

• Should we introduce a shared helper for keyboard shortcut representations in @wordpress/keycodes and @wordpress/keyboard-shortcuts, which would replace the local helper in the editor.

#79560 should already include Storybook examples on how to add keyboard shortcuts correctly; do you think that' that isn't enough and we need an aggregated API ? Also, see this related convo

[Mamaduka]

do you think that' that isn't enough and we need an aggregated API ?

I think it could be helpful. Here I added the getKeyboardShortcut helper for simplicity; happy to follow up with a more general proposal later.

[youknowriad]

Before

After

Hey folks, I don't really know if this is the result of this PR only, but there's a clear design regression here. Can we address that please?

cc @jasmussen @jameskoster

[ciampo]

Hey @youknowriad , this is what I see on latest trunk

Can you confirm if that's the case for you, too? And otherwise how to reproduce that screenshot ?

[youknowriad]

Try the site editor.

[youknowriad]

This still feels like a regression to me:

• Misaligned items with titles
• Some items with text are intended and others are not (I guess it's the icon in the list that impacts that)
• The editor/code switcher also has an icon (a dot) but is not indented.

So the overall feeling is not great, feels under designed

[Mamaduka]

The spacing looks odd because of the Export menu, but I think we discussed that in a different issue: #82346.

P.S. We can probably drop the icon from the export menu (no other item in that group has one), but Riad's comments are valid. That area could look better. cc @fcoveram

Screenshot

[youknowriad]

I guess what I'm saying is that using the new components shouldn't lead to a design regression. If it happens, we should fix the components first or find a way to achieve the same previous results before doing so.

[youknowriad]

Removing the icon doesn't sound like a good solution to me because we'll have the same issue later for block tools or else. So it feels like a systemic issue that we should solve. Components should combine well regardless of whether we use icons or not.

[Mamaduka]

Removing the icon doesn't sound like a good solution to me because we'll have the same issue later for block tools or else.

Yes, the solution should be systematic. I just think we can remove the icon in this particular case.

[ciampo]

This is what it would look like without the icon, which is IMO the main offender

Beyond that, the Menu is behaving as intended, in particular:

• the radio / check icons have their own column track, which "pushes" all item content slightly to the right (so that they stay aligned)
• Items within the same group align their text content, too. That's why the spare "Export" caused the rest of the items in the same group shift to the right.

These behaviors are the result of several rounds of discussions, and they are an attempt at allowing flexibility (ie. mixing and matching check/radio icons + prefix icon + keyboard shortcut + suffix) while also retaining some alignment between items.

It's basically what MacOS does:

The main takeway is, IMO, that we need to curate and do a general pass to all our Menus to make sure that the way items are configured leads to "visually balanced" results. In practical terms, this mostly means to make sure that all items within the same group either have an icon, or they don;t.

One small potential design change that we can consider, is to shift the radio/check icons more to the left (ie closer to the edge), for a potentially better visual balance.

[youknowriad]

There are the main differences with MacOS that make a big difference IMO:

• Nothing except the "check" is misaligned in MacOS (including borders)
• No "group titles" exist on MacOS in my quick testing. I'd say they'd probably be aligned with the text otherwise (without extra indentation)
• In a single group in MacOS, I didn't find any example of some elements with icons but others without icons. I'd say if this is a possibility for us, we shouldn't take inspiration from MacOS because it's a constraint we don't have. If it's a constraint we want to have, we should enforce it / warn or do something about it.

That said, what bothers me the most is that this PR was merged with all the issues known, it feels like a regression for users.

[ciampo]

There are the main differences with MacOS that make a big difference IMO:

That's valuable feedback, and @fcoveram and I will try to absorb it as much as possible in the upcoming days. Thank you 🙏

[Mamaduka]

That said, what bothers me the most is that this PR was merged with all the issues known, it feels like a regression for users.

Without these internal refactors, it's hard to catch real-world cases. Do they have regression risks? Sure. But I think they're minor, and we can polish them before the next major release.

[youknowriad]

It's possible that I'm overreacting a bit :) (I have a tendency to do so), I just don't like design regressions.

[richtabor]

But I think they're minor, and we can polish them before the next major release.

The problem is when this doesn't happen. If Riad did not bring this up, would it just have been released as-is. My expectation is yes, because the PR was merged.

Real-world cases should be the minimum expectation.

[richtabor]

It's basically what MacOS does

It's basically what MacOS does, without the details/accountability that make the MacOS menus remain easily scannable.

The dividers, the text, the icons, all map visually. We're also mixing radio and checkbox.

This version is much more difficult to parse and visually messy. I'm not sure why time was invested here anyway to be honest. Did we expect the new menu to perform better/be easier for users?

[Mamaduka]

The problem is when this doesn't happen. If Riad did not bring this up, would it just have been released as-is. My expectation is yes, because the PR was merged.

I appreciate the feedback and don't disagree. What can we change to get better at discussing/improving these things early? If we've not released the refactoring, I'm sure there will be even less.

[ciampo]

If Riad did not bring this up, would it just have been released as-is. I expect yes, because the PR was merged.

@richtabor the screenshots posted by Riad above don't reflect how the Menu looked like when this PR was merged. There were later PRs merged afterward that introduced some of those "visual regressions".

While Riad's feedback above is general and can be applied to the shared Menu component, the majority of what were called "regressions" were just poor usages of the component (ie having only 1 item out of 4 in the same group with a prefix icon), and not a bug in the component itself.

I hope we can agree that we can't possibly control every PR merged in this repo, especially at the incredible volume/pace of the last few weeks and considering PTO happening here and there, and that we can have conversations such as this one in a collaborative way to discuss and make improvements.

[Mamaduka]

@ciampo, do we have an issue with the immediate polish work? I'll create a PR to remove the icon from the 'Export' menu. It doesn't solve the design system-level problem, but it will align the tool menu item designs.

It's also interesting to see how Google Docs renders similar menus. Checked icons and normal icons are rendered on the same line, but I couldn't find mixed usage - a menu item with an icon + checked status.

Screenshot

[ciampo]

Checked icons and normal icons are rendered on the same line, but I couldn't find mixed usage - a menu item with an icon + checked status.

This was how the previous version of Menu (ie. the private, experimental, ariakit-based one) behaved: checkbox, radio and prefix icon all compete for the same "column" spot.

But then we got feedback about people wanting to show a decorative icon for checkbox / radio items, which is why we adopted this different layout in the new @wordpress/ui Menu, taking macOS as a source of inspiration for the layout rules.

I propose we try to keep the current Menu behaviour and try to apply tweaks to make it better, and re-assess. IMHO, the Menu can definitely look visually pleasing, but it depends on consumers adding icons to all (majority) of menu items, or to add none. Adding only a few icons creates those gaps, and that's something that is on the consumers of the components to do correctly.

If we still don't like it, we can consider moving back to the "Google Docs"-like behavior, which means that checkbox and radio menu items won't be able to display prefix icons.

[jameskoster]

I think we just need to keep the radio/checkbox column clear:

I'd also favor making that column narrower.