Skip to content

UI: Keep inline Autocomplete and Combobox list items clear of the scrollbar in stories - #86673

Merged
mirka merged 6 commits into
trunkfrom
update/autocomplete-inline-stories-scroll-container
Nov 13, 2026
Merged

mirka merged 6 commits into
trunkfrom
update/autocomplete-inline-stories-scroll-container

Conversation

@mirka

@mirka mirka commented Nov 11, 2026 •

Copy link
Copy Markdown
Member

What?

Follow-up to #86338 and #86535

Keeps the items of inline Autocomplete and Combobox lists clear of a classic scrollbar in the stories, and documents how to do it in the story descriptions and on ListBody:

  1. In the Autocomplete "Inline In Popover" story, the emoji grid's scrollbar now sits at the popover's edge instead of against the last column, and the popover's width does not change when the scrollbar appears or disappears.
  2. In the Autocomplete "Inline" and Combobox "Detached Inline" stories, the highlighted item no longer runs into the scrollbar.

Why?

Since #86535, the inline stories scroll inside ListBody. With classic scrollbars, the items are flush with the scrollbar. In a popup, the popup's padding keeps them apart, but an inline list has no such padding. The special characters picker in #86338 had to solve this, and these stories are the examples that consumers copy.

How?

The fix stays in the stories, which explain it, instead of the component adding the space itself. CSS can't tell whether the list overflows, so an automatic gap and gutter would make every inline list end short of the input even when it doesn't scroll. The component also can't know a container's padding, which the popover case needs.

Testing Instructions

  1. Use a browser or OS setting that always shows scrollbars (on macOS, System Settings > Appearance > Show scroll bars > Always).
  2. Open the Storybook story "Components / @wordpress-ui / Form / Primitives / Autocomplete / Inline In Popover" and click "Insert emoji".
  3. The scrollbar sits at the popover's right edge, with space between it and the last column of emojis.
  4. Type "dog". The list stops scrolling, and the popover keeps its width. (Searching for something with no matches still narrows the popover, as on trunk.)
  5. Open the "Autocomplete / Inline" story, focus the input, and press Down. The highlighted item stops short of the scrollbar.
  6. Do the same in the "Combobox / Detached Inline" story.
  7. On the Autocomplete and Combobox docs pages, the descriptions of these stories explain the inline-end padding, scrollbar-gutter, and, for the popover, the negative margin.

Screenshots or screencast

Autocomplete "Inline In Popover", with the last column highlighted:

Before After
Emoji picker popover with the last column of emojis directly against the scrollbar Emoji picker popover with space between the last column of emojis and the scrollbar at the popover's edge

Autocomplete "Inline In Popover", after searching for "dog":

Before After
Emoji picker popover narrower than before the search Emoji picker popover at the same width as before the search

Autocomplete "Inline", with the first item highlighted:

Before After
Inline command list with the highlighted item running into the scrollbar Inline command list with a gap between the highlighted item and the scrollbar

Combobox "Detached Inline", with the first item highlighted:

Before After
Inline fruit list with the highlighted item running into the scrollbar Inline fruit list with a gap between the highlighted item and the scrollbar

…opover story

The emoji grid's last column sat against a classic scrollbar, and the
popover narrowed when search results stopped overflowing. Reserve the
scrollbar's gutter, and extend the list body into the popover's padding
so the scrollbar sits at the popover's edge.
@mirka mirka added [Type] Developer Documentation Documentation for developers [Package] UI /packages/ui labels Nov 11, 2026
@mirka mirka self-assigned this Nov 11, 2026
@github-actions

github-actions Bot commented Nov 11, 2026 •

Copy link
Copy Markdown

🤖 PR meta 🤖

Preview in WordPress Playground Preview in Storybook

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

Total Size: 8.65 MB

3640e05 Run

⚡ Performance

Show the results

Client side metrics exclude the server response time.

front-end-block-theme

Metric 0f45b6d trunk % Change
timeToFirstByte 46.35 ms +3.13% -2.91% 45.75 ms +4.26% -1.75% 1.31%
largestContentfulPaint 76 ms +7.89% -5.26% 72 ms +13.89% -0% 5.56%
lcpMinusTtfb 27.7 ms +25.99% -3.25% 26.55 ms +12.43% -4.9% 4.33%
wpBeforeTemplate 23.13 ms +6.31% -1.64% 23.27 ms +5.46% -1.85% -0.6%
wpTemplate 18.68 ms +7.6% -1.98% 18.67 ms +5.68% -2.89% 0.05%
wpTotal 42.56 ms +3.64% -2.84% 42.16 ms +4.39% -1.9% 0.95%
wpMemoryUsage 7.75 MB +0% -0% 7.68 MB +0% -0% 0.81%
wpDbQueries 16 +0% -0% 16 +0% -0% 0%

front-end-classic-theme

Metric 0f45b6d trunk % Change
timeToFirstByte 38.25 ms +6.41% -1.31% 38.65 ms +8.41% -1.68% -1.03%
largestContentfulPaint 72 ms +2.78% -0% 72 ms +2.78% -5.56% 0%
lcpMinusTtfb 33.85 ms +1.18% -3.1% 31.85 ms +4.87% -4.87% 6.28%
wpBeforeTemplate 20.85 ms +7.39% -0.91% 20.75 ms +11.57% -1.64% 0.48%
wpTemplate 14.55 ms +2.54% -1.72% 14.68 ms +5.11% -3.07% -0.89%
wpTotal 35.48 ms +6.14% -1.44% 35.73 ms +8.4% -2.13% -0.7%
wpMemoryUsage 6.44 MB +0% -0% 6.37 MB +0% -0% 0.99%
wpDbQueries 13 +0% -0% 13 +0% -0% 0%

media-processing

Metric 0f45b6d trunk % Change
mediaProcessingJpeg 404.23 ms +0.88% -0.34% 407.44 ms +1.48% -0.98% -0.79%
mediaProcessingAvif 6337.36 ms +0.23% -0.28% 6312.49 ms +0.33% -0.26% 0.39%
mediaProcessingJpegToAvif 4353.39 ms +0.22% -0.07% 4341.15 ms +0.09% -0.33% 0.28%

media-upload

Metric 0f45b6d trunk % Change
jpegUploadProcessing 1512.12 ms +33.41% -1.92% 1491.54 ms +0.53% -1.4% 1.38%
pngUploadProcessing 253.21 ms +5.03% -4.97% 244.76 ms +1.2% -1.34% 3.45%
largeJpegUploadProcessing 1482.97 ms +0.35% -1.69% 1470.59 ms +0.28% -0.55% 0.84%
multipleImageUploadProcessing 1618.96 ms +2.82% -0.45% 1614.02 ms +0.83% -0.58% 0.31%

post-editor

Metric 0f45b6d trunk % Change
serverResponse 290.12 ms +0.99% -9.8% 284.87 ms +4.89% -8.53% 1.84%
firstPaint 307.47 ms +12.81% -4.99% 306.14 ms +1.38% -2.38% 0.43%
domContentLoaded 601.91 ms +0.69% -1.16% 595.62 ms +2.4% -3.41% 1.06%
loaded 602.83 ms +0.7% -1.15% 596.57 ms +2.41% -3.39% 1.05%
firstContentfulPaint 346.73 ms +0.69% -3.9% 339.78 ms +3.04% -1.89% 2.05%
firstBlock 1590.64 ms +2.15% -1.11% 1558.46 ms +1.89% -1.44% 2.06%
type 14.28 ms +6.58% -9.38% 15.33 ms +7.24% -5.09% -6.85%
typeWithoutInspector 12.74 ms +3.22% -7.54% 14.57 ms +5.35% -14.34% -12.56%
typeWithTopToolbar 16.14 ms +2.97% -4.71% 16.98 ms +4.36% -5.83% -4.95%
typeContainer 6.2 ms +6.13% -8.55% 6.5 ms +7.54% -14.92% -4.62%
focus 80.6 ms +9.62% -4.94% 77.55 ms +8.97% -4.77% 3.93%
firstFocus 158.2 ms +0% -0% 187 ms +0% -0% -15.4%
selectAll 254.16 ms +0.68% -0.83% 226.17 ms +0.53% -0.85% 12.38%
undo 22.73 ms +5.98% -8.23% 19.43 ms +11.89% -4.99% 16.98%
listViewOpen 50.36 ms +4.37% -7.29% 47.6 ms +2.69% -6.49% 5.8%
inserterOpen 32.25 ms +9.05% -3.04% 26.49 ms +6.49% -3.44% 21.74%
inserterHover 9.36 ms +5.24% -4.17% 7.81 ms +9.73% -6.66% 19.85%
inserterSearch 7.19 ms +3.89% -4.45% 6.16 ms +8.28% -5.36% 16.72%
loadPatterns 500.07 ms +3.6% -2.84% 427.57 ms +4.79% -4.22% 16.96%
wpTotal 283.02 ms +1% -10.02% 278.09 ms +4.84% -8.87% 1.77%
wpMemoryUsage 14.81 MB +0% -0% 14.74 MB +0% -0% 0.46%
wpDbQueries 55 +0% -0% 55 +0% -0% 0%

site-editor

Metric 0f45b6d trunk % Change
serverResponse 485.1 ms +0.95% -1.56% 459.53 ms +1.77% -6.67% 5.56%
firstPaint 467.98 ms +2.65% -10.77% 409.74 ms +14.27% -4.39% 14.21%
domContentLoaded 845.97 ms +6.15% -1.09% 817.32 ms +2.43% -0.59% 3.51%
loaded 847.06 ms +6.13% -1.05% 818.48 ms +2.41% -0.59% 3.49%
firstContentfulPaint 474.15 ms +9.93% -2.19% 461.6 ms +1.43% -1.59% 2.72%
firstBlock 2607.76 ms +4.96% -0.83% 2538.83 ms +0.94% -2.63% 2.72%
type 17.02 ms +5.23% -3.94% 17.13 ms +1.46% -9.63% -0.64%
navigate 115.92 ms +1.67% -3.19% 115.03 ms +1.38% -4.61% 0.77%
loadPatterns 1336.51 ms +12.89% -2.34% 1304.85 ms +5.35% -6.28% 2.43%
loadPages 955.18 ms +2.73% -1.07% 938.52 ms +2.81% -1.75% 1.78%
wpTotal 475.64 ms +0.92% -1.6% 450.16 ms +1.77% -6.84% 5.66%
wpMemoryUsage 12.82 MB +0% -0% 12.76 MB +0% -0% 0.46%
wpDbQueries 45 +0% -0% 45 +0% -0% 0%

3640e05 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.

Undo restores the post selection when another synced entity is loaded (RTC WebSocket) in /test/e2e/specs/editor/collaboration/collaboration-undo-redo.spec.ts, passed after 1 failed attempt.
Error: expect(received).toMatchObject(expected)

- Expected  - 2
+ Received  + 2

  Object {
    "attributeKey": "content",
    "blockIndex": 0,
    "content": "abcdef",
-   "endOffset": 3,
-   "offset": 3,
+   "endOffset": 6,
+   "offset": 6,
  }

Call Log:
- Timeout 5000ms exceeded while waiting on the predicate
    at /home/runner/work/gutenberg/gutenberg/test/e2e/specs/editor/collaboration/collaboration-undo-redo.spec.ts:363:5
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

3640e05 Run

…opover story

The gutter only prevents width changes caused by the scrollbar. The
popover still narrows when no results match.
In an inline Autocomplete or Combobox list, the items reach a classic
scrollbar. Give the inline stories' list bodies an inline-end padding
and a stable scrollbar gutter. Document the technique on ListBody,
including the negative margin for a padded container such as a Popover,
in place of the inline in popover story's description.
@mirka mirka changed the title Autocomplete: Keep the scrollbar clear of the grid in the inline in popover story UI: Keep inline Autocomplete and Combobox list items clear of the scrollbar in stories Nov 12, 2026
The constant only held comments that have since moved to ListBody, and
the other inline stories set their list body styles inline.
@mirka
mirka marked this pull request as ready for review November 12, 2026 16:24
@mirka
mirka requested a review from a team as a code owner November 12, 2026 16:24

@ciampo ciampo left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

LGTM 🚀

Could ListBody leave a small gap between the highlighted item and a classic scrollbar by default? That would save consumers from adding the same padding to each inline list.

Do you think it would be useful if the popover story explained how scrollbar-gutter: stable keeps the picker the same width as results are filtered and how the negative inline-end margin moves the scrollbar to the popover’s edge?

Storybook does not show a subcomponent's description, so the ListBody
guidance never reached the docs page. Restore the explanation in the
inline in popover story, and explain the padding and gutter in the
inline Autocomplete and Combobox stories.
Phrase the inline story descriptions as steps for consumers, so they
don't read as default behavior, and split the ListBody description into
shorter paragraphs.
@mirka

mirka commented Nov 13, 2026

Copy link
Copy Markdown
Member Author

Could ListBody leave a small gap between the highlighted item and a classic scrollbar by default? That would save consumers from adding the same padding to each inline list.

This was also preferable to me, but unfortunately it leaves an unnecessary space if the list never overflows. So it's basically something the consumer needs to opt into, knowing that the their list overflows.

Do you think it would be useful if the popover story explained how scrollbar-gutter: stable keeps the picker the same width as results are filtered and how the negative inline-end margin moves the scrollbar to the popover’s edge?

Added 👍

@mirka
mirka enabled auto-merge (squash) November 13, 2026 09:48
@mirka
mirka merged commit ddf1c72 into trunk Nov 13, 2026
80 of 83 checks passed
@mirka
mirka deleted the update/autocomplete-inline-stories-scroll-container branch November 13, 2026 09:55
@github-actions github-actions Bot added this to the Gutenberg 24.5 milestone Nov 13, 2026
@ciampo

ciampo commented Nov 13, 2026

Copy link
Copy Markdown
Contributor

This was also preferable to me, but unfortunately it leaves an unnecessary space if the list never overflows. So it's basically something the consumer needs to opt into, knowing that the their list overflows.

Gotcha, if we see a lot of reuse maybe we could turn it into a prop / data attribute, with the component providing the styles

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

Labels

[Package] UI /packages/ui [Type] Developer Documentation Documentation for developers

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants