Skip to content

List View: Replace useFixedWindowList with a colocated window hook - #87065

Open
Mamaduka wants to merge 8 commits into
trunkfrom
refactor/list-view-windowing
Open

Mamaduka wants to merge 8 commits into
trunkfrom
refactor/list-view-windowing

Conversation

@Mamaduka

@Mamaduka Mamaduka commented Nov 19, 2026 •

Copy link
Copy Markdown
Member

What?

See #87019

Replaces useFixedWindowList in List View with useListViewWindow, a hook colocated with the component. Home, End, Page Up and Page Down pressed in another field no longer scroll the list, a list panel that grows without a window resize no longer leaves blank rows, and a focused row keeps focus when it scrolls out of view.

Why?

The old hook moved the render window for every row scrolled, which re-rendered the whole tree each time. It also listened for navigation keys on the window and re-measured only on window resize. List View was its only consumer.

How?

The window now moves in chunks: only when fewer than 10 spare rows remain past the viewport, and then far enough to render 40. Scroll is captured on the document so the hook follows whichever ancestor scrolls the list, a ResizeObserver watches the list's ancestors, and navigation keys are left to TreeGrid and the browser. When the window moves, the hook also records the focused row, which ListViewBranch keeps mounted. This is a minor optimization for scrolling long lists; each window move is a longer frame than before, so very fast scrolling can drop a few more frames. useFixedWindowList itself is unchanged.

Testing Instructions

  1. Open a post with a long list of blocks, for example 200 paragraphs.
  2. Open Document Overview and scroll the list quickly in both directions. Rows are always shown, with no blank gaps.
  3. Scroll the list down a little and click a row. Open the Settings sidebar, expand Advanced, click the HTML anchor field, then press End and Page Down. The list keeps its scroll position.
  4. In dev tools, add max-height: 200px to .editor-list-view-sidebar, scroll the list down, then remove the rule. Rows fill the taller panel.

Testing Instructions for Keyboard

  1. With the list focused, press Page Down. The list scrolls by a page.
  2. Press End, then Home. Focus moves to the last row, then the first.
  3. Press Arrow Down a few times, scroll the list far down with the mouse wheel, then scroll back up. The same row is still focused.

Use of AI Tools

Assisted by Claude.

@Mamaduka
Mamaduka requested a review from ellatrix as a code owner November 19, 2026 07:22
@github-actions

github-actions Bot commented Nov 19, 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: Mamaduka <mamaduka@git.wordpress.org>
Co-authored-by: lancewillett <lancewillett@git.wordpress.org>
Co-authored-by: noruzzamans <noruzzaman@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: +374 B (0%)

Total Size: 8.68 MB

📦 View Changed
Filename Size Change
build/scripts/block-editor/index.min.js 556 kB +374 B (+0.07%)

afd5306 Run

⚡ Performance

Show the results

Client side metrics exclude the server response time.

front-end-block-theme

Metric 7cb5c07 trunk % Change
timeToFirstByte 58.6 ms +3.5% -3.67% 57.05 ms +2.37% -3.94% 2.72%
largestContentfulPaint 90 ms +11.11% -2.22% 88 ms +9.09% -4.55% 2.27%
lcpMinusTtfb 29.95 ms +29.72% -2.84% 30.75 ms +24.72% -12.03% -2.6%
wpBeforeTemplate 30.75 ms +5.85% -3.41% 29.68 ms +4.72% -3.84% 3.61%
wpTemplate 23.35 ms +4.15% -5.74% 23.04 ms +1% -5.43% 1.35%
wpTotal 54.53 ms +3.37% -3.48% 52.86 ms +1.93% -3.69% 3.16%
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 7cb5c07 trunk % Change
timeToFirstByte 47.2 ms +5.08% -1.8% 47.85 ms +2.82% -2.93% -1.36%
largestContentfulPaint 84 ms +4.76% -2.38% 84 ms +2.38% -4.76% 0%
lcpMinusTtfb 36.95 ms +6.77% -7.04% 34.8 ms +5.89% -3.3% 6.18%
wpBeforeTemplate 26.92 ms +9.25% -1.86% 27.1 ms +2.4% -1.51% -0.66%
wpTemplate 16.79 ms +3.93% -5% 16.92 ms +3.66% -3.72% -0.77%
wpTotal 44.23 ms +4.57% -2.46% 44.71 ms +3.04% -3.31% -1.07%
wpMemoryUsage 6.44 MB +0% -0% 6.40 MB +0% -0% 0.56%
wpDbQueries 13 +0% -0% 13 +0% -0% 0%

media-processing

Metric 7cb5c07 trunk % Change
mediaProcessingJpeg 405.6 ms +3.27% -0.79% 405.62 ms +0.43% -0.52% 0%
mediaProcessingAvif 6175.75 ms +0.04% -0.29% 6174.48 ms +0.14% -0.35% 0.02%
mediaProcessingJpegToAvif 4242.43 ms +0.19% -0.29% 4249.2 ms +0.17% -0.24% -0.16%

media-upload

Metric 7cb5c07 trunk % Change
jpegUploadProcessing 1989.44 ms +3.46% -22.76% 1991.49 ms +1.39% -17.08% -0.1%
pngUploadProcessing 277.83 ms +1.87% -5.45% 281.27 ms +4.44% -5.12% -1.22%
largeJpegUploadProcessing 1987.78 ms +0.48% -0.76% 1988.52 ms +0.11% -0.36% -0.04%
multipleImageUploadProcessing 2077.67 ms +0.3% -0.43% 2086.75 ms +1.07% -0.8% -0.44%

post-editor

Metric 7cb5c07 trunk % Change
serverResponse 400.04 ms +3% -6.95% 396.09 ms +1.81% -7.96% 1%
firstPaint 398.51 ms +19.61% -12.68% 378.97 ms +6.09% -7.74% 5.16%
domContentLoaded 795.92 ms +3.52% -1.93% 765.33 ms +0.56% -1.94% 4%
loaded 797.06 ms +3.53% -1.92% 766.42 ms +0.56% -1.95% 4%
firstContentfulPaint 451.6 ms +9.24% -3.71% 427.46 ms +2.48% -1.52% 5.65%
firstBlock 2011.69 ms +2.38% -2.4% 1945.48 ms +1.55% -2.93% 3.4%
type 17.57 ms +5.01% -9.33% 17.22 ms +2.32% -13.24% 2.03%
typeWithoutInspector 16.81 ms +4.1% -12.02% 17.5 ms +4% -11.26% -3.94%
typeWithTopToolbar 22.59 ms +8.68% -10.23% 21.16 ms +5.77% -7.33% 6.76%
typeContainer 8.24 ms +14.68% -9.22% 7.66 ms +14.75% -8.49% 7.57%
focus 119.35 ms +4.22% -7.54% 109.19 ms +4.51% -6.98% 9.3%
firstFocus 247.08 ms +0% -0% 242.66 ms +0% -0% 1.82%
selectAll 325.48 ms +1.71% -0.73% 328.59 ms +2.52% -3.05% -0.95%
undo 29.14 ms +4.12% -8.61% 27.27 ms +9.53% -2.9% 6.86%
listViewOpen 58.95 ms +4.12% -9.13% 70.06 ms +8.19% -6.74% -15.86%
inserterOpen 39.16 ms +7.66% -4.09% 39.92 ms +7.49% -3.36% -1.9%
inserterHover 11.28 ms +10.37% -7.45% 11.49 ms +11.05% -8.7% -1.83%
inserterSearch 8.16 ms +4.9% -4.29% 8.31 ms +7.82% -4.93% -1.81%
loadPatterns 659.63 ms +2.11% -8.65% 648.28 ms +7.5% -4.17% 1.75%
wpTotal 390.33 ms +3.1% -7.09% 386.52 ms +1.84% -8.2% 0.99%
wpMemoryUsage 14.81 MB +0% -0% 14.77 MB +0% -0% 0.25%
wpDbQueries 55 +0% -0% 55 +0% -0% 0%

site-editor

Metric 7cb5c07 trunk % Change
serverResponse 381.52 ms +6.43% -5.48% 404.01 ms +0.88% -10.42% -5.57%
firstPaint 458.93 ms +7.75% -13.1% 452.29 ms +4.25% -12.3% 1.47%
domContentLoaded 833.92 ms +6.37% -2.86% 830.6 ms +0.93% -1.55% 0.4%
loaded 834.98 ms +6.37% -2.85% 831.65 ms +0.93% -1.54% 0.4%
firstContentfulPaint 476.06 ms +10.35% -2.6% 469.61 ms +0.45% -1.26% 1.37%
firstBlock 2501.13 ms +5.95% -2.09% 2476.14 ms +0.26% -0.37% 1.01%
type 17.74 ms +12.23% -8.57% 18.42 ms +5.97% -6.03% -3.69%
navigate 115.39 ms +1.65% -0.58% 111.33 ms +11.84% -0.59% 3.65%
loadPatterns 1453.4 ms +3.22% -7.84% 1249.63 ms +2.65% -12.94% 16.31%
loadPages 946.96 ms +2.23% -3.08% 924.81 ms +0.99% -0.45% 2.4%
wpTotal 370.86 ms +6.61% -5.61% 393.4 ms +0.89% -10.77% -5.73%
wpMemoryUsage 12.82 MB +0% -0% 12.79 MB +0% -0% 0.25%
wpDbQueries 45 +0% -0% 45 +0% -0% 0%

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

List in /test/e2e/specs/editor/blocks/query.spec.js, passed after 1 failed attempt.
Error: expect(received).toMatchObject(expected)

- Expected  - 22
+ Received  +  1

  Array [
    Object {
-     "innerBlocks": Array [
-       Object {
-         "innerBlocks": Array [
-           Object {
-             "name": "core/post-title",
-           },
-           Object {
-             "name": "core/post-featured-image",
-           },
-           Object {
-             "name": "core/post-excerpt",
-           },
-           Object {
-             "name": "core/separator",
-           },
-           Object {
-             "name": "core/post-date",
-           },
-         ],
-         "name": "core/post-template",
-       },
-     ],
+     "innerBlocks": Array [],
      "name": "core/query",
    },
  ]

Call Log:
- Timeout 5000ms exceeded while waiting on the predicate
    at /home/runner/work/gutenberg/gutenberg/test/e2e/specs/editor/blocks/query.spec.js:226:42
does not select blocks in the canvas preview when editing from the sidebar 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 select synced pattern in /test/e2e/specs/editor/various/writing-flow.spec.js, passed after 1 failed attempt.
Error: expect(locator).toBeFocused() failed

Locator:  locator('[name="editor-canvas"]').contentFrame().locator('[data-type="core/block"]')
Expected: focused
Received: inactive
Timeout:  5000ms

Call log:
  - Expect "toBeFocused" locator('[name="editor-canvas"]').contentFrame().locator('[data-type="core/block"]') with timeout 5000ms
  - waiting for locator('[name="editor-canvas"]').contentFrame().locator('[data-type="core/block"]')
    14 × locator resolved to <div tabindex="0" role="document" draggable="true" data-title="Pattern" data-type="core/block" data-is-drop-zone="true" aria-label="Block: Pattern" id="block-bdeaa5d8-aed2-4a3b-b162-fdbb3c06968f" data-block="bdeaa5d8-aed2-4a3b-b162-fdbb3c06968f" class="block-editor-block-list__block wp-block is-selected is-reusable block-library-block__reusable-block-container wp-block-block block-editor-block-list__layout">…</div>
       - unexpected value "inactive"

    at /home/runner/work/gutenberg/gutenberg/test/e2e/specs/editor/various/writing-flow.spec.js:1464:5

afd5306 Run

@github-actions github-actions Bot added the [Package] Block editor /packages/block-editor label Nov 19, 2026
@Mamaduka Mamaduka added the [Type] Performance Related to performance efforts label Nov 19, 2026
Comment on lines +10 to +11
const MIN_BUFFER_ROWS = 10;
const MAX_BUFFER_ROWS = 40;

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

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

These were tuned with a perf probe. A minimum of 20 or 30 dropped more frames (28 or 50 against 19). A maximum of 70 halved the dropped frames, but each one got longer (54ms against 42ms).

Comment on lines +114 to +118
if ( coversRows( listWindow, first, last, 0 ) ) {
setFixedListWindow( nextWindow );
} else {
flushSync( () => setFixedListWindow( nextWindow ) );
}

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

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

Always using flushSync would let us drop the ref, but it measured worse: jank went up 31%, and dropped frames doubled with a 4x CPU throttle. startTransition for the deferred case made no difference.


const { getBlock, getSelectedBlockClientIds } =
useSelect( blockEditorStore );
const { visibleBlockCount } = useSelect(

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

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

The new hook doesn't need the total row count, so List View no longer subscribes to the global block count.

Mamaduka and others added 2 commits November 19, 2026 11:25
Move the window in chunks and follow whichever ancestor scrolls the
list.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
Set the content with editor.setContent, check for blank rows with a
viewport assertion, and mark the tests to remove before merge.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
Read the focused row when the window moves and keep it rendered, so
scrolling it out of view does not drop focus.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
@noruzzamans

Copy link
Copy Markdown
Member

Tested on macOS (Chrome).

Followed the testing instructions with a post of 200 paragraphs:

  • Fast scrolling in List View: Smooth virtualized rendering, no blank rows or gaps.
  • Keyboard navigation: Home jumps directly to the first row, and End jumps to the 200th row as expected.
  • Focus retention: Scrolled off-screen rows retain their focus when scrolling back into view.
  • Input field isolation: Pressing Home and End while editing inside the HTML anchor field no longer unexpectedly scrolls the List View.

Everything works cleanly and as described.

Screen.Recording.2026-11-19.at.3.43.54.PM.mp4

@Mamaduka

Copy link
Copy Markdown
Member Author

Thanks, @noruzzamans!

The List View open metric changes also look promising.

Screenshot

CleanShot 2026-11-19 at 14 07 40

Drop the itemInView closure left over from useFixedWindowList, and cover
native scrolling across browsers with the wheel test alone.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
@noruzzamans

Copy link
Copy Markdown
Member

Thanks, @noruzzamans!

The List View open metric changes also look promising.

Screenshot

CleanShot 2026-11-19 at 14 07 40

That ~22% speedup on listViewOpen is great to see!

Comment on lines +52 to +57
const [ fixedListWindow, setFixedListWindow ] = useState< FixedListWindow >(
() => ( {
start: 0,
end: Math.ceil( window.innerHeight / BLOCK_LIST_ITEM_HEIGHT ),
} )
);

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

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

Reposting, since the earlier comment got detached when this was inlined. Sizing the first window from innerHeight avoids reading layout while the list opens. The cost is about 3 extra rows on a 1080px viewport, which opens about 1ms slower than trunk. 720px and 1440px open faster.

Comment on lines +91 to +94
const focusedRow =
ownerDocument.activeElement?.closest< HTMLElement >(
'[data-block]'
);

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

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

The first attempt kept the focused block in state and passed it through context, which re-rendered the whole tree on every focus move. Reading it here costs nothing, since the tree already re-renders when the window moves. A scroll probe measured the same main-thread work with and without the pin. Trunk has the same focus drop, so this isn't a regression fix for the new hook.

Comment on lines +162 to +163
const blockInView =
blockListPosition >= start && blockListPosition < end;

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

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

itemInView was a leftover from the useFixedWindowList API. A plain range does the same job and measured no difference in the scroll probe.

It is the only test that checks the key still pages the list now that
the browser handles it.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>

@lancewillett lancewillett 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.

Before removing the temporary E2E cases, could you keep one browser test for useListViewWindow? Open the dropdown far down a scrolled page, scroll its panel 1,000 pixels, and assert that row 35 is visible.

In a local Chrome comparison, the first row appeared on open in all three runs with both hooks. After scrolling, row 35 was missing in all three runs with the hook from before #87019 and visible in all three with this PR. That assertion catches the regression and lets us remove the temporary editor scenario. Dropdown assertions

AI review · gpt-6

Mamaduka and others added 2 commits November 19, 2026 17:47
Starting to observe the scroll container from inside the observer's own
callback made the browser report a ResizeObserver loop error on mount.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
@Mamaduka

Copy link
Copy Markdown
Member Author

Thanks for the review, @lancewillett!

Added use-list-view-window.browser.test.tsx with the dropdown case, plus one for a panel that grows without a window resize, since that fix would also lose its test. The temporary e2e cases are removed.

Writing the test surfaced a ResizeObserver loop error on mount. The hook started observing the scroll container from inside its own callback. I couldn’t reproduce it when testing manually or with the e2e tests, only in the browser test. It now observes the list’s ancestors up front, the same way #87019 does.

The page scroll could land before the panel was clipped, which grows
the window past the row the test checked.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>

This branch has not been deployed

No deployments
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 [Type] Performance Related to performance efforts

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants