List View: Add smart expansion for nested blocks #74319

JosVelasco · 2026-01-01T18:38:16Z

What?

Adds a Gutenberg experiment that implements dynamic expansion depth adjustment for the List View. When enabled, the List View automatically collapses deeper nesting levels to maintain optimal performance and usability.

Why?

The List View can become difficult to navigate and slow to render when dealing with deeply nested block structures (issue #53004). Users need a way to work with complex page hierarchies without performance degradation or overwhelming visual clutter.

How?

Implements dynamic expansion as a Gutenberg experiment (off by default)
Adds experiment toggle in WordPress Admin → Gutenberg → Experiments
Exposes user-configurable "Maximum auto-expanded blocks" setting in Editor Preferences → General → List View (default: 20, range: 5-200)
Uses performance optimizations: early exits when block count is within threshold, leverages Core's cached getGlobalBlockCount() selector
Includes debug mode for development (DEBUG_DYNAMIC_EXPANSION flag in code)

Testing Instructions

Test Case 1: Enable Experiment and Basic Functionality

Go to WordPress Admin → Gutenberg → Experiments
Enable "List View: Dynamic expansion"
Create a post with nested blocks (e.g., Group → Columns → Group → Paragraph)
Add enough nested blocks to exceed 20 total visible items
Open List View
Expected: Deeper levels are automatically collapsed to keep visible count ≤ 20
You can manually expand/collapse as needed

Test Case 2: Settings Panel

Open Editor Preferences (⋮ menu → Preferences)
Go to General tab
Look for "Maximum auto-expanded blocks" section under List View
Expected: Number input field visible (range 5-200, default 20)
Change value to 10
Refresh page and open List View
Expected: Expansion behavior now uses the new threshold of 10 blocks

Test Case 3: Small Pages

Create a simple post with < 20 blocks
Open List View
Expected: All blocks fully expanded (no collapsing needed)

Video

expand-nesting.mp4

github-actions · 2026-01-01T18:38:55Z

👋 Thanks for your first Pull Request and for helping build the future of Gutenberg and WordPress, @JosVelasco! In case you missed it, we'd love to have you join us in our Slack community.

If you want to learn more about WordPress development in general, check out the Core Handbook full of helpful information.

Implements automatic depth adjustment for List View based on block count as a Gutenberg experiment. When enabled, the List View will automatically collapse deeper levels when the visible block count exceeds a configurable threshold (default: 20 blocks). Key features: - Gutenberg experiment with admin toggle - User-configurable max visible blocks setting (5-200, default 20) - Performance optimizations with early exits and Core selector integration - Settings panel in Editor Preferences > General > List View - Debug mode for development (DEBUG_DYNAMIC_EXPANSION flag) The feature improves performance and usability for sites with deeply nested block structures while maintaining full expansion for simpler pages. Fixes WordPress#53004.

github-actions · 2026-01-06T23:58:00Z

Warning: Type of PR label mismatch

To merge this PR, it requires exactly 1 label indicating the type of PR. Other labels are optional and not being checked here.

Required label: Any label starting with [Type].
Labels found: [Package] Block editor, [Package] Edit Post, First-time Contributor.

Read more about Type labels in Gutenberg. Don't worry if you don't have the required permissions to add labels; the PR reviewer should be able to help with the task.

github-actions · 2026-01-06T23:58:02Z

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: JosVelasco <josvelasco@git.wordpress.org>
Co-authored-by: Mamaduka <mamaduka@git.wordpress.org>
Co-authored-by: andrewserong <andrewserong@git.wordpress.org>

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

Mamaduka · 2026-01-08T05:41:18Z

Thank you, @JosVelasco! This is an interesting experiment.

The List View renders a fixed number of items initially, using virtualization for large lists. I'm not sure if providing a way to set a threshold above this number would be beneficial. Maybe instead of providing this option, we use a smart default that matches the maximum number of initial items.

Here's the code responsible for this logic:

gutenberg/packages/block-editor/src/components/list-view/index.js

Lines 323 to 340 in 3cd52a4

    
           // List View renders a fixed number of items and relies on each having a fixed item height of 36px. 
        
           // If this value changes, we should also change the itemHeight value set in useFixedWindowList. 
        
           // See: https://github.com/WordPress/gutenberg/pull/35230 for additional context. 
        
           const [ fixedListWindow ] = useFixedWindowList( 
        
           	elementRef, 
        
           	BLOCK_LIST_ITEM_HEIGHT, 
        
           	visibleBlockCount, 
        
           	{ 
        
           		// Ensure that the windowing logic is recalculated when the expanded state changes. 
        
           		// This is necessary because expanding a collapsed block in a short list view can 
        
           		// switch the list view to a tall list view with a scrollbar, and vice versa. 
        
           		// When this happens, the windowing logic needs to be recalculated to ensure that 
        
           		// the correct number of blocks are rendered, by rechecking for a scroll container. 
        
           		expandedState, 
        
           		useWindowing: true, 
        
           		windowOverscan: 40, 
        
           	} 
        
           );

cc @andrewserong

andrewserong · 2026-01-09T06:31:58Z

+1 this is an impressive exploration. It'd be good to loop in some designers for feedback when you're ready as the behaviour in the list view can be quite challenging to get intuitive, but I appreciate that a lot of thought has gone into this one!

Something I'm wondering from looking at the code change — is there a way to simplify this, i.e. for it to be a binary "expand all if less total blocks than a threshold" rather than figuring out the exact level of depth to expand to? Or does it feel key that it should take care to handle particular levels of depth? My main concern is about whether the additional complexity is worth the benefit, though the logic here is quite clever.

JosVelasco · 2026-01-10T15:10:48Z

Hi @andrewfleming and @Mamaduka. Thanks for your comments! Before experimenting further, please take a look at this simpler alternative.
#74507

List View: Add smart expansion for nested blocks

7cb640f

github-actions bot added [Package] Block editor /packages/block-editor First-time Contributor Pull request opened by a first-time contributor to Gutenberg repository labels Jan 1, 2026

JosVelasco added 2 commits January 1, 2026 12:46

List View: Add dynamic expansion for nested blocks

6ffde4b

github-actions bot added the [Package] Edit Post /packages/edit-post label Jan 6, 2026

JosVelasco added 3 commits January 6, 2026 16:29

Fix PHP coding standards - add newline at end of file

0bce5fc

Fix PHP coding standards - ensure exactly one newline at EOF

12d124c

Fix PHP coding standards - ensure one newline at EOF

ce58fbb

JosVelasco marked this pull request as ready for review January 6, 2026 23:57

JosVelasco requested review from ellatrix and spacedmonkey as code owners January 6, 2026 23:57

Mamaduka added [Type] Enhancement A suggestion for improvement. [Feature] List View Menu item in the top toolbar to select blocks from a list of links. labels Jan 8, 2026

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

List View: Add smart expansion for nested blocks #74319

List View: Add smart expansion for nested blocks #74319

Uh oh!

JosVelasco commented Jan 1, 2026 •

edited

Loading

Uh oh!

github-actions bot commented Jan 1, 2026

Uh oh!

github-actions bot commented Jan 6, 2026

Uh oh!

github-actions bot commented Jan 6, 2026 •

edited

Loading

Uh oh!

Mamaduka commented Jan 8, 2026

Uh oh!

andrewserong commented Jan 9, 2026

Uh oh!

JosVelasco commented Jan 10, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

List View: Add smart expansion for nested blocks #74319

Are you sure you want to change the base?

List View: Add smart expansion for nested blocks #74319

Uh oh!

Conversation

JosVelasco commented Jan 1, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What?

Why?

How?

Testing Instructions

Test Case 1: Enable Experiment and Basic Functionality

Test Case 2: Settings Panel

Test Case 3: Small Pages

Video

Uh oh!

github-actions bot commented Jan 1, 2026

Uh oh!

github-actions bot commented Jan 6, 2026

Uh oh!

github-actions bot commented Jan 6, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Mamaduka commented Jan 8, 2026

Uh oh!

andrewserong commented Jan 9, 2026

Uh oh!

JosVelasco commented Jan 10, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

JosVelasco commented Jan 1, 2026 •

edited

Loading

github-actions bot commented Jan 6, 2026 •

edited

Loading