Skip to content

DropdownMenu: Align item layouts with the design system - #85861

Closed
ciampo wants to merge 13 commits into
trunkfrom
codex/components-menu-selection-layout
Closed

ciampo wants to merge 13 commits into
trunkfrom
codex/components-menu-selection-layout

Conversation

@ciampo

@ciampo ciampo commented Oct 28, 2026 •

Copy link
Copy Markdown
Contributor

Follow-up to #85831.

What?

Move selection checks before the labels in MenuItemsChoice, ToolsPanel, Widgets preference toggles, the style state menu, and the legacy image aspect-ratio picker.

Why?

Checks should line up with their labels, including labels with descriptions. Toggling a choice should keep the label and menu width steady.

How?

Gutenberg supplies the check through the existing MenuItem icon props. Its internal row style reserves space when unchecked and aligns action labels in mixed menus. Plugins can continue to supply their own icons. For new menus in Gutenberg, use Menu from @wordpress/ui.

Testing Instructions

  1. In Storybook, open DropdownMenu → Mixed Content. Switch editor modes and toggle Show details. The checks should line up with the titles. Labels and menu width should stay steady, and action icons and shortcuts should keep their positions. Repeat in RTL.
  2. In the block editor, open a Paragraph block's Typography options. Toggle a control and reset a changed value. Reset actions should align with the option labels and have no check.
  3. In a Button block's State menu, choose Hover and toggle Preview on canvas. Both checks should use the same leading column.
  4. With a classic theme, open Appearance → Widgets → Options and toggle Top toolbar. In a consumer of the legacy image editor, reopen the aspect-ratio picker and select the current ratio. The menu should close.

Testing Instructions for Keyboard

Focus a menu button and press Enter. Use the arrow keys to reach a choice, then press Enter to activate it. Press Escape in the open menu and check that focus returns to the button.

Screenshots or screencast

Playground integration checks

These Playground captures are from the earlier implementation at 4f6a562da3b, using WordPress 7.1.4 and PHP 8.3.36. The block-state menu now puts the state choices on the leading side as well.

ToolsPanel reset action Block-state preview Widgets preferences
ToolsPanel reset action in Playground Block-state preview toggle in Playground Widgets preferences in Playground

Earlier Chromium Storybook captures at 720 × 650. The before images use trunk fc3fc980f94. The after images show the previous implementation of the leading-check layout.

Example Before After
Independent selections Multi-selection before Multi-selection after
Mixed radio selections, checkbox, actions, shortcuts, and suffix Mixed content before Mixed content after
Standalone choice with description and shortcut Standalone choice before Standalone choice after
ToolsPanel selections ToolsPanel before ToolsPanel after
ToolsPanel reset suffix ToolsPanel reset before ToolsPanel reset after
Theme and unchanged-composition comparisons
Example Before After
Mixed content in RTL with WordPress global CSS RTL mixed content before RTL mixed content after
Mixed content in the dark theme Dark mixed content before Dark mixed content after
Caller-supplied control icons Controls before Controls after
Custom MenuItem with a description Custom description before Custom description after

Related @wordpress/ui references: rich items, radio items, and checkbox items.

Use of AI Tools

Implemented and verified with Codex.

@github-actions github-actions Bot added the [Package] Components /packages/components label Oct 28, 2026
@github-actions

github-actions Bot commented Oct 28, 2026 •

Copy link
Copy Markdown

🤖 PR meta 🤖

Preview in WordPress Playground

🎉 Props

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: ciampo <mciampini@git.wordpress.org>
Co-authored-by: mirka <0mirka00@git.wordpress.org>

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


Props Bot commands

You can trigger Props Bot actions by commenting on this PR:

  • @propsbot add <username> to give props to a GitHub user. Requires write access.
  • @propsbot remove <username> to leave a user out of the props. Requires write access.
  • @propsbot refresh to refresh this list. Adding the props-bot label works too.

Updated as activity occurs, without notifying anyone named here. Add the props-bot label to refresh.

📦 Bundle size

Size Change: +1.59 kB (+0.02%)

Total Size: 8.66 MB

📦 View Changed
Filename Size Change
build/scripts/block-editor/index.min.js 555 kB +21 B (0%)
build/scripts/components/index.min.js 338 kB +40 B (+0.01%)
build/scripts/preferences/index.min.js 2.99 kB +18 B (+0.61%)
build/styles/components/style-rtl.css 18.5 kB +351 B (+1.94%)
build/styles/components/style-rtl.min.css 15.6 kB +406 B (+2.67%)
build/styles/components/style.css 18.5 kB +355 B (+1.95%)
build/styles/components/style.min.css 15.6 kB +400 B (+2.63%)

44eebe8 Run

⚡ Performance

Show the results

Client side metrics exclude the server response time.

front-end-block-theme

Metric d5df4b7 trunk % Change
timeToFirstByte 43 ms +3.02% -1.86% 42.75 ms +9.82% -3.74% 0.58%
largestContentfulPaint 70 ms +2.86% -8.57% 70 ms +11.43% -5.71% 0%
lcpMinusTtfb 25.35 ms +14% -11.05% 26.5 ms +11.51% -13.4% -4.34%
wpBeforeTemplate 22.47 ms +2.94% -2.31% 22.06 ms +5.35% -2.77% 1.86%
wpTemplate 17.12 ms +3.33% -4.32% 17.18 ms +3.96% -6.58% -0.35%
wpTotal 39.85 ms +3.19% -2.99% 39.39 ms +10.33% -3.66% 1.17%
wpMemoryUsage 7.75 MB +0% -0% 7.71 MB +0% -0% 0.45%
wpDbQueries 16 +0% -0% 16 +0% -0% 0%

front-end-classic-theme

Metric d5df4b7 trunk % Change
timeToFirstByte 35.95 ms +6.95% -3.62% 35.85 ms +7.11% -4.32% 0.28%
largestContentfulPaint 64 ms +6.25% -0% 64 ms +6.25% -3.13% 0%
lcpMinusTtfb 28.95 ms +1.73% -3.28% 28.7 ms +5.92% -8.54% 0.87%
wpBeforeTemplate 19.09 ms +13.36% -0.73% 19.4 ms +15.21% -1.7% -1.6%
wpTemplate 13.24 ms +4.31% -3.78% 12.76 ms +8.46% -4.7% 3.76%
wpTotal 33.15 ms +6.24% -3.29% 33.1 ms +7.67% -4.29% 0.15%
wpMemoryUsage 6.44 MB +0% -0% 6.40 MB +0% -0% 0.56%
wpDbQueries 13 +0% -0% 13 +0% -0% 0%

media-processing

Metric d5df4b7 trunk % Change
mediaProcessingJpeg 325.97 ms +1.43% -0.58% 326.05 ms +0.81% -0.1% -0.02%
mediaProcessingAvif 4849.86 ms +0.14% -0.38% 4852.89 ms +0.4% -0.16% -0.06%
mediaProcessingJpegToAvif 3394.93 ms +0.21% -0.36% 3385.19 ms +0.19% -0.15% 0.29%

media-upload

Metric d5df4b7 trunk % Change
jpegUploadProcessing 1459.59 ms +1.16% -1.16% 1451.73 ms +1.47% -0.68% 0.54%
pngUploadProcessing 238.47 ms +1.73% -2.12% 244.92 ms +23.65% -4.21% -2.63%
largeJpegUploadProcessing 1443.76 ms +0.6% -0.88% 1439.33 ms +0.58% -0.61% 0.31%
multipleImageUploadProcessing 1489.86 ms +1.04% -0.18% 1508.37 ms +0.98% -0.8% -1.23%

post-editor

Metric d5df4b7 trunk % Change
serverResponse 265.43 ms +1.69% -5.48% 301.5 ms +2.99% -9.16% -11.96%
firstPaint 272.85 ms +3.1% -9.19% 352.3 ms +2.62% -6.65% -22.55%
domContentLoaded 504.27 ms +4.69% -3% 637.48 ms +3.4% -2.53% -20.9%
loaded 504.96 ms +4.72% -3% 638.48 ms +3.39% -2.53% -20.91%
firstContentfulPaint 285.5 ms +5.44% -1.83% 360.82 ms +6.96% -1.97% -20.87%
firstBlock 1374.56 ms +1.74% -1.84% 1699.36 ms +2.61% -1.63% -19.11%
type 14.93 ms +6.83% -9.65% 17.6 ms +3.18% -9.77% -15.17%
typeWithoutInspector 14.87 ms +7.67% -8.14% 16.54 ms +10.58% -9.55% -10.1%
typeWithTopToolbar 17.4 ms +6.67% -8.28% 20.79 ms +8.56% -3.17% -16.31%
typeContainer 6.46 ms +12.07% -7.89% 7 ms +9.86% -1.43% -7.71%
focus 86.33 ms +7.17% -3.64% 89.05 ms +5.54% -4.32% -3.05%
firstFocus 163.87 ms +0% -0% 194.61 ms +0% -0% -15.8%
selectAll 283.81 ms +4.6% -1.21% 281.73 ms +0.02% -3.38% 0.74%
undo 25.11 ms +7.57% -6.37% 24.24 ms +6.19% -6.93% 3.59%
listViewOpen 57.82 ms +6.17% -0.73% 55.09 ms +11.44% -5.88% 4.96%
inserterOpen 35.16 ms +7.25% -10.07% 34.25 ms +9.78% -3.42% 2.66%
inserterHover 10.57 ms +10.6% -4.92% 9.99 ms +10.51% -7.41% 5.81%
inserterSearch 8.19 ms +8.91% -3.54% 7.92 ms +11.74% -7.45% 3.41%
loadPatterns 518.34 ms +5.63% -2.18% 499.45 ms +11.64% -3.75% 3.78%
wpTotal 258.66 ms +1.77% -5.56% 294.39 ms +2.83% -9.38% -12.14%
wpMemoryUsage 14.81 MB +0% -0% 14.77 MB +0% -0% 0.25%
wpDbQueries 55 +0% -0% 55 +0% -0% 0%

site-editor

Metric d5df4b7 trunk % Change
serverResponse 398.63 ms +1.86% -8.48% 398.88 ms +0.6% -8.33% -0.06%
firstPaint 391.35 ms +11.14% -6.6% 386.79 ms +11.6% -5.22% 1.18%
domContentLoaded 786.62 ms +1.83% -0.18% 777.46 ms +1.36% -0.31% 1.18%
loaded 787.68 ms +1.82% -0.18% 778.45 ms +1.38% -0.29% 1.19%
firstContentfulPaint 435.94 ms +5.38% -1.12% 431.55 ms +0.86% -1.02% 1.02%
firstBlock 2386.04 ms +8.64% -1.65% 2329.61 ms +1.47% -0.67% 2.42%
type 16.7 ms +10.96% -5.33% 17.05 ms +8.56% -8.62% -2.05%
navigate 117.91 ms +0.75% -4.04% 109.4 ms +4.67% -0.97% 7.78%
loadPatterns 1229.72 ms +15.39% -4.51% 1265.57 ms +2.94% -8.25% -2.83%
loadPages 913.48 ms +2.1% -0.93% 931.51 ms +2.57% -1.03% -1.94%
wpTotal 389.54 ms +1.66% -8.69% 389.67 ms +0.7% -8.47% -0.03%
wpMemoryUsage 12.82 MB +0% -0% 12.79 MB +0% -0% 0.25%
wpDbQueries 45 +0% -0% 45 +0% -0% 0%

44eebe8 Run

🏁 Flaky tests

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.

As a user I want to be able to add multiple close buttons so that users can close the overlay from different positions in /test/e2e/specs/site-editor/navigation-overlay-template-part.spec.js, passed after 1 failed attempt.
Error: expect(locator).toHaveCount(expected) failed

Locator:  getByRole('button', { name: 'Close' })
Expected: 2
Received: 1
Timeout:  5000ms

Call log:
  - Expect "toHaveCount" getByRole('button', { name: 'Close' }) with timeout 5000ms
  - waiting for getByRole('button', { name: 'Close' })
    14 × locator resolved to 1 element
       - unexpected value "1"

    at /home/runner/work/gutenberg/gutenberg/test/e2e/specs/site-editor/navigation-overlay-template-part.spec.js:228:33
a navigation superseded by the traversal discharges to idle in /test/e2e/specs/interactivity/router-navigation-lifecycle.spec.ts, passed after 1 failed attempt.
SyntaxError: Unexpected token 'o', "not hydrated" is not valid JSON
    at readLog (/home/runner/work/gutenberg/gutenberg/test/e2e/specs/interactivity/router-navigation-lifecycle.spec.ts:28:14)
    at /home/runner/work/gutenberg/gutenberg/test/e2e/specs/interactivity/router-navigation-lifecycle.spec.ts:47:24
    at waitForLogLength (/home/runner/work/gutenberg/gutenberg/test/e2e/specs/interactivity/router-navigation-lifecycle.spec.ts:46:2)
    at /home/runner/work/gutenberg/gutenberg/test/e2e/specs/interactivity/router-navigation-lifecycle.spec.ts:693:5
does not select blocks in the canvas preview when editing from the sidebar (Site Editor v2) in /test/e2e/specs/site-editor/navigation-sidebar-list-view.spec.js, passed after 1 failed attempt.
Error: expect(locator).toBeFocused() failed

Locator: getByRole('combobox', { name: 'Search or type URL' })
Expected: focused
Timeout: 5000ms
Error: element(s) not found

Call log:
  - Expect "toBeFocused" getByRole('combobox', { name: 'Search or type URL' }) with timeout 5000ms
  - waiting for getByRole('combobox', { name: 'Search or type URL' })

    at LinkControl.useLinkControlSearch (/home/runner/work/gutenberg/gutenberg/test/e2e/specs/site-editor/navigation-sidebar-list-view.spec.js:416:47)
    at /home/runner/work/gutenberg/gutenberg/test/e2e/specs/site-editor/navigation-sidebar-list-view.spec.js:179:21
should apply a named font size using the font size buttons in /test/e2e/specs/editor/various/font-size-picker.spec.js, passed after 1 failed attempt.
Error: expect(received).toBe(expected) // Object.is equality

- Expected  - 2
+ Received  + 2

- <!-- wp:paragraph {"fontSize":"large"} -->
+ <!-- wp:paragraph {"fontSize":"medium"} -->
- <p class="has-large-font-size">Paragraph to be made "large"</p>
+ <p class="has-medium-font-size">Paragraph to be made "large"</p>
  <!-- /wp:paragraph -->

Call Log:
- Timeout 5000ms exceeded while waiting on the predicate
    at /home/runner/work/gutenberg/gutenberg/test/e2e/specs/editor/various/font-size-picker.spec.js:153:6
should reset a named font size using input field in /test/e2e/specs/editor/various/font-size-picker.spec.js, passed after 1 failed attempt.
Error: expect(received).toBe(expected) // Object.is equality

- Expected  - 2
+ Received  + 2

- <!-- wp:paragraph {"fontSize":"small"} -->
+ <!-- wp:paragraph {"fontSize":"tiny"} -->
- <p class="has-small-font-size">Paragraph with font size reset using input field</p>
+ <p class="has-tiny-font-size">Paragraph with font size reset using input field</p>
  <!-- /wp:paragraph -->

Call Log:
- Timeout 5000ms exceeded while waiting on the predicate
    at /home/runner/work/gutenberg/gutenberg/test/e2e/specs/editor/various/font-size-picker.spec.js:216:6
should reset a named font size using the tools panel menu in /test/e2e/specs/editor/various/font-size-picker.spec.js, passed after 1 failed attempt.
Error: expect(received).toBe(expected) // Object.is equality

- Expected  - 2
+ Received  + 2

- <!-- wp:paragraph {"fontSize":"medium"} -->
+ <!-- wp:paragraph {"fontSize":"small"} -->
- <p class="has-medium-font-size">Paragraph with font size reset using tools panel menu</p>
+ <p class="has-small-font-size">Paragraph with font size reset using tools panel menu</p>
  <!-- /wp:paragraph -->

Call Log:
- Timeout 5000ms exceeded while waiting on the predicate
    at /home/runner/work/gutenberg/gutenberg/test/e2e/specs/editor/various/font-size-picker.spec.js:178:6
should restore an older revision in /test/e2e/specs/editor/various/revisions.spec.js, passed after 1 failed attempt.
Error: expect(received).toMatchObject(expected)

- Expected  - 1
+ Received  + 1

  Array [
    Object {
      "attributes": Object {
-       "content": "Original content - Updated content - Autosaved",
+       "content": "Original content",
      },
      "name": "core/paragraph",
    },
  ]

Call Log:
- Timeout 5000ms exceeded while waiting on the predicate
    at /home/runner/work/gutenberg/gutenberg/test/e2e/specs/editor/various/revisions.spec.js:146:5

44eebe8 Run

@ciampo ciampo self-assigned this Oct 28, 2026
@ciampo ciampo changed the title MenuItemsChoice, ToolsPanel: Move selection marks before labels DropdownMenu: Align item layouts with the design system Oct 29, 2026
@ciampo
ciampo marked this pull request as ready for review October 30, 2026 21:25
@ciampo
ciampo requested a review from a team as a code owner October 30, 2026 21:25
@ciampo ciampo added [Type] Enhancement A suggestion for improvement. Backport to WP 7.2 Beta/RC Pull request that needs to be backported to the WordPress major release that's currently in beta [Type] Bug An existing feature does not function as intended and removed [Type] Enhancement A suggestion for improvement. labels Oct 30, 2026

@mirka mirka left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

To be honest I think it would be risky to get this into 7.2 at this stage, given the potential for unexpected things to happen. There seem to be many possible content compositions of this DropdownMenu component, which makes it hard to assess the effects of the layout change without actually seeing all the different compositions in context.

Even the ToolsPanel for example, it's hard to say the new layout is an improvement over the current. Which might even mean that it may be safer to leave this component alone, backport or not, and have consumers replace the existing usages with the new Menu layout at their discretion so it doesn't cause noticeably degraded experiences. I think there should at least be an audit of the existing compositions before moving forward with a component-level change.

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The existing Multi Selection story still renders checks on the right, while MenuItemsChoice and ToolsPanel now put them on the left. I think we should update that?

But also, the existence of this pattern worries me, because we can't do anything about third-party usage that already does this. It looks like we even have two such cases in the codebase.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Both stories now use the new MenuItem showSelectionIndicator prop, and legacy trailing-check coverage lives in tests. The preference toggles, aspect-ratio choices, and block-state preview toggle use the same composition in 4f6a562da3b.

@ciampo

ciampo commented Nov 9, 2026

Copy link
Copy Markdown
Contributor Author

Gotcha re. not backporting - hopefully we won't get additional feedback about the legacy and new Menu components not feeling consistent in 7.2.

I've added the composition audit and refreshed comparisons, and made the direct MenuItem indicator opt-in so existing custom-icon compositions stay supported. The built-in choices and migrated consumers share that implementation, with usage guidance and changelog notes.

@ciampo
ciampo requested a review from mirka November 10, 2026 16:52

@mirka mirka left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

A new API at this point is interesting. What's the plan for these components? I would have expected these to be unrecommended soon and nudged to move to Menu. Or are we going to keep MenuItem* around? Asking because it was unclear whether this is just a quick way to migrate in-repo usage, or if we are actually encouraging consumers to migrate to this new prop rather than moving to Menu.

I kind of expected an opt in to the new layout to mean a migration to Menu. But maybe there are use cases not covered by that?

@ciampo

ciampo commented Nov 11, 2026 •

Copy link
Copy Markdown
Contributor Author

It's all a balance. Especially if we don't want to rush with migrating all components (a point made earlier today re. the SelectControl migration), this new API was a way to allow consumers of legacy components to switch to a more consistent layout - including third-party.

I'm also ok with not adding this API, the trade-off is that the potential visual inconsistency between Menu components will be more noticeable.

@ciampo
ciampo force-pushed the codex/components-menu-selection-layout branch from 138a3a6 to ed52de3 Compare November 12, 2026 17:33
@ciampo

ciampo commented Nov 12, 2026

Copy link
Copy Markdown
Contributor Author

I've dropped showSelectionIndicator. The built-in choices and the Gutenberg menus touched here now use the existing icon props to put the check before the label and keep the label in place when unchecked.

Plugin authors can keep their existing MenuItem compositions. For new menus in Gutenberg, we should reach for Menu from @wordpress/ui as soon as it's recommended. WDYT ?

@ciampo
ciampo requested a review from mirka November 12, 2026 18:09
@ciampo ciampo removed the Backport to WP 7.2 Beta/RC Pull request that needs to be backported to the WordPress major release that's currently in beta label Nov 16, 2026
Let the Components stylesheet place the check so independently updated menus keep their existing layout with older styles. Give the radio choices their own group in the mixed-menu example and document the supported icon type.
@ciampo
ciampo force-pushed the codex/components-menu-selection-layout branch from bb510ff to 44eebe8 Compare November 16, 2026 19:27
@github-actions
github-actions Bot requested a review from aduth November 16, 2026 19:28
} }
role="menuitemradio"
isSelected={ ratio === value }
className="components-menu-item__selection-row"

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It looks like we're treating this like a utility class now. Doesn't this go against the standard guidance to not have class names cross component boundaries?

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Not immediately sure why the utility class name approach had to be taken, but if that's a necessity for some reason, I think that gives us a stronger case to prefer migration to Menu rather than try to alter DropdownMenu/MenuItem.

@ciampo

ciampo commented Nov 20, 2026

Copy link
Copy Markdown
Contributor Author

As also discussed in #85960 , I'm closing this PR since the changes required to reach layout consistency in DropdownMenu add considerable complexity and risk causing regressions in existing consumers. In other words, it seems that the downsides are not worth the upsides.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

[Package] Block editor /packages/block-editor [Package] Components /packages/components [Package] Preferences /packages/preferences [Type] Bug An existing feature does not function as intended

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants