Media: Add a settings dialog to the Media Library toolbar. by t-hamano · Pull Request #12932 · WordPress/wordpress-develop

t-hamano · 2026-08-07T11:43:23Z

Alternatives to Media: Add a checkbox to toggle infinite scrolling in the media modal #12795
Trac ticket: https://core.trac.wordpress.org/ticket/65775

Overview

WordPress core does not yet seem to have an API for rendering what are known as popovers. This PR instead attempts to render a settings dialog for the media library using the HTML native dialog element. The only concern is that this PR is the first to introduce a UI using the dialog element.

New APIs

PHP:
- wp_ajax_set_media_library_settings()
JavaScript
- wp.media.view.LibrarySettings
- wp.media.view.settings.librarySettings

Use of AI Tools

Note

This PR is a prototype. Almost all of the code in this PR was generated by Claude. If we find the approach taken in this PR to be reasonable, I would like to review all of the code.

Screenshots

The "Infinite Scrolling" personal option could only be reached from the user profile screen, far from the grid it affects. This adds a toggle next to the search field in the attachments browser toolbar that opens a modal dialog with that option, in both the grid and the media modal. The dialog is a native `dialog` element opened with `showModal()`, so the focus trap, the Escape handling, the backdrop and the focus restore on close come from the platform rather than from a hand-rolled implementation. Keyboard events are kept from reaching the media modal, whose own Escape handler and focus manager would otherwise fight the dialog. Toggling the checkbox saves the preference over Ajax and applies it in place: `wp.media.view.Attachments` can now bind and unbind its scroll handler after creation, and `wp.media.view.AttachmentsBrowser` swaps the Load more view in and out, so no page reload is needed. Both views now read the setting at creation time instead of capturing it when the module loads. The toggle is not rendered when a `media_library_infinite_scrolling` filter callback overrides the user preference, since the control would have no effect. Co-Authored-By: Claude <noreply@anthropic.com>

github-actions · 2026-08-07T11:46:10Z

Test using WordPress Playground

The changes in this pull request can previewed and tested using a WordPress Playground instance.

WordPress Playground is an experimental project that creates a full WordPress instance entirely within the browser.

Some things to be aware of

All changes will be lost when closing a tab with a Playground instance.
All changes will be lost when refreshing the page.
A fresh instance is created each time the link below is clicked.
Every time this pull request is updated, a new ZIP file containing all changes is created. If changes are not reflected in the Playground instance,
it's possible that the most recent build failed, or has not completed. Check the list of workflow runs to be sure.

For more details about these limitations and more, check out the Limitations page in the WordPress Playground documentation.

Test this pull request with WordPress Playground.

Allows space for the media library settings toggle.

Improves experience for voice control

joedolson · 2026-08-09T19:51:10Z

I pushed a few minor visual tweaks and changed the label configuration to avoid using an implicit label. Overall, I think this is very workable.

I noticed that the modal is not actually restricting focus, so that will need to be adjusted, but this is going in a direction that I think is viable.

Copilot

Pull request overview

Adds a Media Library toolbar control that opens a native HTML <dialog> for editing per-user Media Library preferences (starting with infinite scrolling), and wires those preference changes through AJAX to update behavior immediately in the attachments browser.

Changes:

Adds a toolbar “settings” toggle and <dialog> templates for Media Library settings.
Introduces a new core AJAX action to persist the user’s infinite scrolling preference.
Updates media views (Attachments/AttachmentsBrowser) and CSS to support toggling between infinite scrolling and “Load more” without a reload.

Reviewed changes

Copilot reviewed 11 out of 11 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
src/wp-includes/media.php	Exposes filtered vs user preference values and passes dialog config (nonce, state) to JS.
src/wp-includes/media-template.php	Adds Underscore templates for the settings toggle and `<dialog>` UI.
src/wp-includes/css/media-views.css	Styles the settings toggle/dialog and adjusts load-more visibility behavior.
src/wp-admin/includes/ajax-actions.php	Adds `wp_ajax_set_media_library_settings()` handler to save the preference.
src/wp-admin/css/media.css	Adjusts grid toolbar layout to accommodate the new toggle in narrow viewports.
src/wp-admin/admin-ajax.php	Registers `set-media-library-settings` as a core POST AJAX action.
src/js/media/views/library-settings.js	Implements the toolbar control, dialog open/close behavior, and AJAX save.
src/js/media/views/attachments/browser.js	Listens for preference changes and swaps infinite-scroll vs load-more UI live.
src/js/media/views/attachments.js	Makes infinite scrolling togglable after initialization; cleans up scroll bindings.
src/js/_enqueues/wp/media/views.js	Registers the new `LibrarySettings` view in the media views bundle.
Gruntfile.js	Adds build mapping for the new `library-settings.js` file.

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

Ensures isFiltered compares like types when a callback returns 0/1.

Covers nonce failure, missing capability, the missing value and the stored preference.

…y settings

… state

… open

…rolling filter

…he frame

…JSHint

…pdate

…log from resizing

t-hamano · 2026-08-10T10:53:28Z

I believe I've addressed all the issues I could think of. We should be ready for review now.

github-actions · 2026-08-10T10:53:42Z

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.

Core Committers: Use this line as a base for the props when committing in SVN:

Props wildworks, joedolson, tyxla, annezazu, fcoveram, joen, 369work.

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

joedolson · 2026-08-10T14:35:05Z

Pushed two changes on narrower viewports - the button position below 782px and the button size between 782px and 900px.

joedolson

I have two items that I think are non-blocking changes, and can be iterated based on feedback.

joedolson · 2026-08-10T14:41:29Z

+					</label>
+				</p>
+				<p class="description" id="{{ data.infiniteScrollingId }}-description"><?php _e( 'Load more media items automatically when scrolling, instead of using a Load more button.' ); ?></p>
+				<p class="media-library-settings__status" role="status"></p>


The role of 'status' is equivalent to aria-live="polite", and I don't think that's quite right here. Mostly because of the extended aria-description, which means that when you toggle the control, you have to wait for the full label & description to finish reading before the status announcement occurs. For that reason, I'd be more inclined to use role="alert".

@afercia Do you have an opinion here?

joedolson · 2026-08-10T14:44:06Z

+/**
+ * Media Library settings
+ */
+.wp-core-ui .button.media-library-settings__toggle {


Having the button visually embedded in the search field is something I'm not really sure about. It somewhat conveys the idea that this is specifically search options, rather than general media library options.

annezazu · 2026-08-10T20:13:00Z

I don’t think this is very discoverable or well connected to the media library. As Joe notes above, it feels more about search options. I’m not comfortable right now proceeding with this, especially with where we are in the release cycle too.

joedolson · 2026-08-10T20:21:38Z

@annezazu Honestly, the positioning of the button is a relatively trivial part of this; relocating that is very doable. The more important part, in my opinion, is:

Is a settings toggle a good idea? (In my opinion yes, this is an appropriate place for this.)
Is the dialog functional, accessible, and clear? (Also in my opinion, yes.)

But I'm not convinced by the location; I think it was better when it wasn't directly inlined with the search field, however, and think it probably should be even earlier in the modal.

… modal. Co-Authored-By: Claude <noreply@anthropic.com>

t-hamano · 2026-08-11T01:42:06Z

it feels more about search options

We could indicate that the button is an independent option by placing everything except the toggle button on the left side, but I believe this would require a significant CSS change. I believe the structure of the media toolbar needs a fundamental overhaul.

fcoveram · 2026-08-11T08:46:29Z

The button location shown in @t-hamano's message above looks good to me. The layout is similar to that in DataViews (Picker) and the media upload UX.

tyxla · 2026-08-11T08:54:51Z

@jasmussen I just requested review from you here but saw @fcoveram's feedback late. Thank you both!

jasmussen · 2026-08-11T08:58:24Z

Happy to ship this as well! Thanks all.

t-hamano · 2026-08-11T09:00:13Z

We could indicate that the button is an independent option by placing everything except the toggle button on the left side, but I believe this would require a significant CSS change. I believe the structure of the media toolbar needs a fundamental overhaul.

To be honest, I'm hesitant to make major CSS changes around the media view and media toolbar right now because the CSS is overly complex 😅 While we might refactor the media-related UI with modern CSS in the future, I don't want to do that right before the final RC release. Let's find an acceptable compromise for the 7.1 release.

tyxla

Thanks for working on this @t-hamano 🙌 The feature is a nice quality-of-life win.

My main hesitation is timing rather than the code. We're at RC2, and this adds a new public JS API, a new AJAX endpoint, and runtime layout changes to one of the most-exercised screens in the admin, one that a lot of plugins hook into. The issues I highlight in review are in runtime the happy path, which makes me suspect there's more we haven't found yet.

Could we get some broad manual testing before this lands? Toggling the setting mid-session in both grid mode and the modal, across browsers, with filters and search active, and with at least one plugin that customises the media views. If that comes back clean, great. But if it feels like it needs more than a quick pass it could very well be a 7.2 item.

tyxla · 2026-08-11T09:13:07Z

+			$( this.options.scrollElement ).on( 'scroll', this.scroll );
+
+			// The list may already be scrolled past the point where more are loaded.
+			this.scroll();


Noting that this.scroll() never checks this.options.infiniteScrolling so if there's already a queued throttled callback or pending collection.more(), they might call scroll() again, which will run unchecked. We might want to add a this.options.infiniteScrolling check to scroll() itself.

Fixed in 431a1b9

tyxla · 2026-08-11T09:17:23Z

+	 * @type {boolean}
+	 */
+	isFiltered: !! settings.librarySettings &&
+		Boolean( settings.infiniteScrolling ) !== Boolean( settings.librarySettings.infiniteScrolling ),


Hmm, aren't we risking losing the filter precedence here? Disabling the checkbox here changes the UI to "Load More" despite the filter requiring infinite scrolling.

Fixed in cf528d3. I made it explicit whether a filter exists using has_filter.

tyxla · 2026-08-11T09:18:30Z

+
+		this.setStatus( __( 'Saving…' ) );
+
+		wp.ajax.post( 'set-media-library-settings', {


Multiple concurrent saves can result in saving the wrong value. Might need some throttling or disabling if a request is in progress here.

Fixed in 93997ba

tyxla · 2026-08-11T09:20:14Z

+			view.setStatus( enabled ?
+				__( 'Infinite scrolling is on.' ) :
+				__( 'Infinite scrolling is off.' )
+			);


Is this yet another place that might be out of sync with isFiltered? Looks like we're not covering the case when a filter has forced that infinite scroll is "on".

I am considering this, and I have two proposals.

Notify that the filter is enabled when settings are updated. For example, Setting saved. Infinite scrolling is currently controlled by a plugin or theme.

When filtered, the toggle button should not be displayed at all.

To me, the first option is more clear.

tyxla · 2026-08-11T09:21:17Z

+		}
+
+		this.attachments.setInfiniteScrolling( enabled );
+		this.$el.toggleClass( 'has-load-more', ! enabled );


We might need to cover a few more items/classes based on this logic, like .more-loaded, .found-media, and .new-media for example.

Fixed in 8562d2a

tyxla · 2026-08-11T09:40:57Z

+ * A toolbar control opening a modal dialog with the personal options for the
+ * Media Library.
+ *
+ * @since 7.1.0


Considering the 7.1 branch is only for bug fixes at this point, I doubt if this will make it. Should we consider it for 7.2?

This will need to be agreed upon and decided among the release leads.

tyxla · 2026-08-11T09:43:53Z

+}
+
+.wp-core-ui .media-toolbar-primary > .media-library-settings__toggle {
+	margin-left: 8px;


Isn't the toggle absolute? Why use margins?

Nice catch, this is something I forgot to remove when I absolutely positioned the toggle. Removed in cd6074a

tyxla · 2026-08-11T09:44:04Z

+}
+
+.wp-core-ui .mode-grid .media-toolbar-primary > .media-library-settings__toggle {
+	margin-left: 0;


Same question as above.

Removed in cd6074a

tyxla · 2026-08-11T09:47:20Z

+		this.attachments.setInfiniteScrolling( enabled );
+		this.$el.toggleClass( 'has-load-more', ! enabled );


Wouldn't enabling infinite scrolling in the modal always flash the spinner and fetch an extra page? Should we swap those 2 lines to address that?

…ling is off Co-Authored-By: Claude <noreply@anthropic.com>

…akes precedence Co-Authored-By: Claude <noreply@anthropic.com>

…he checkbox Co-Authored-By: Claude <noreply@anthropic.com>

…rolling Co-Authored-By: Claude <noreply@anthropic.com>

…absolutely positioned Co-Authored-By: Claude <noreply@anthropic.com>

…g so it does not fetch an extra page Co-Authored-By: Claude <noreply@anthropic.com>

t-hamano · 2026-08-11T11:37:20Z

@tyxla Thanks for the review!

My main hesitation is timing rather than the code. We're at RC2, and this adds a new public JS API, a new AJAX endpoint, and runtime layout changes to one of the most-exercised screens in the admin, one that a lot of plugins hook into. The issues I highlight in review are in runtime the happy path, which makes me suspect there's more we haven't found yet.

I agree with this. While I understand the importance of improving accessibility, there is also a risk of causing problems by introducing new APIs.

This might go against the decision, but personally I propose punting this PR to 7.2. There is too little time to prepare.

cc @annezazu @joedolson

t-hamano · 2026-08-11T12:02:08Z

Could we get some broad manual testing before this lands? Toggling the setting mid-session in both grid mode and the modal, across browsers, with filters and search active, and with at least one plugin that customises the media views.

I tested the layout changes when the Media Library Assistant plugin, which extends the media toolbar, was enabled.

Before

After

369work · 2026-08-11T15:46:41Z

Test in Playground

I tested PR #12932 for the first time, and I don't think it would be immediately obvious to users that they need to click the gear icon.

I think the “Enable infinite scrolling” checkbox could be placed somewhere more visible and intuitive, so users can discover the setting more easily.

annezazu · 2026-08-11T17:29:57Z

Coming here to say that I agree we need to punt this from the 7.1 release. I am just uncomfortable with these kinds of changes at this stage of the release process when we need utmost stability. I also think this is worthy of being considered for a point release for 7.1 and that's something we can pursue without waiting months until 7.2.

t-hamano mentioned this pull request Aug 7, 2026

Media: Add a checkbox to toggle infinite scrolling in the media modal #12795

Open

joedolson added 3 commits August 9, 2026 14:39

Adjust search input width

a98eea4

Allows space for the media library settings toggle.

Switch label from implicit to explicit

9251623

Improves experience for voice control

Adjust paragraph alignment & and cover narrow viewports

b0bb18a

t-hamano requested a lite review from Copilot August 10, 2026 07:06

Copilot started reviewing on behalf of t-hamano August 10, 2026 07:06 View session

Copilot AI reviewed Aug 10, 2026

View reviewed changes

Comment thread src/wp-includes/media.php Outdated

Comment thread src/js/media/views/library-settings.js

Comment thread src/wp-includes/media-template.php

Comment thread src/wp-admin/includes/ajax-actions.php

Comment thread src/wp-admin/css/media.css Outdated

t-hamano added 17 commits August 10, 2026 16:17

Cast media_library_infinite_scrolling filter result to boolean

2b58600

Ensures isFiltered compares like types when a callback returns 0/1.

Tests: Add coverage for the Media Library settings Ajax handler

a10841e

Covers nonce failure, missing capability, the missing value and the stored preference.

Tests: Follow the ajax test docblock conventions for the Media Librar…

3aac1c6

…y settings

Media: Make the infinite scrolling checkbox label state the resulting…

d280e56

… state

Media: Scope the search field max-width to the grid mode toolbar

837d3b4

Media: Drop the redundant comment on the library settings media data

ee61aef

Media: Send the library settings data only to users who can upload files

5421a07

Media: Let the library settings Ajax error messages reach the dialog

d22db3c

Docs: Correct the Media Library settings since tags to 7.1.0

382cdfe

Media: Sync the library settings dialog with the stored value on each…

e70b2c5

… open

Media: Show the library settings toggle regardless of the infinite sc…

f407c53

…rolling filter

Media: Move the library settings dialog out of the toolbar and into t…

49ba43d

…he frame

Docs: Trim the Media Library settings view docblocks to their summaries

961d5b7

Media: Adjust the Media Library settings toggle and dialog styles

b67cddb

Media: Use Boolean() in the library settings filter check to satisfy …

dd4fe91

…JSHint

Media: Drop the redundant comment on the library settings user meta u…

eb9a031

…pdate

Media: Restore the library settings status min-height to keep the dia…

739c979

…log from resizing

t-hamano marked this pull request as ready for review August 10, 2026 10:53

joedolson added 2 commits August 10, 2026 09:28

Improve button alignment on sub 782px viewport

2b23278

Fix button sizing between 782 and 900 px

c8617bc

joedolson approved these changes Aug 10, 2026

View reviewed changes

Media: Adjust search field and settings toggle placement in the media…

2ca898f

… modal. Co-Authored-By: Claude <noreply@anthropic.com>

tyxla requested a review from jasmussen August 11, 2026 08:54

tyxla reviewed Aug 11, 2026

View reviewed changes

t-hamano and others added 6 commits August 11, 2026 19:33

Media: Bail out of the attachments scroll handler when infinite scrol…

431a1b9

…ling is off Co-Authored-By: Claude <noreply@anthropic.com>

Media: Report the infinite scrolling filter explicitly so it always t…

cf528d3

…akes precedence Co-Authored-By: Claude <noreply@anthropic.com>

Media: Serialize library settings saves so the stored value matches t…

93997ba

…he checkbox Co-Authored-By: Claude <noreply@anthropic.com>

Media: Clear the Load more highlighting when switching to infinite sc…

8562d2a

…rolling Co-Authored-By: Claude <noreply@anthropic.com>

Media: Drop the settings toggle margins left over from before it was …

cd6074a

…absolutely positioned Co-Authored-By: Claude <noreply@anthropic.com>

Media: Swap to the scrolling layout before enabling infinite scrollin…

155999b

…g so it does not fetch an extra page Co-Authored-By: Claude <noreply@anthropic.com>

Merge branch 'trunk' into add/media-library-settings-dialog

fe09da6


		this.setStatus( __( 'Saving…' ) );

		wp.ajax.post( 'set-media-library-settings', {

		this.attachments.setInfiniteScrolling( enabled );
		this.$el.toggleClass( 'has-load-more', ! enabled );

Uh oh!

Conversation

t-hamano commented Aug 7, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Overview

New APIs

Use of AI Tools

Screenshots

Uh oh!

github-actions Bot commented Aug 7, 2026

Test using WordPress Playground

Some things to be aware of

Uh oh!

joedolson commented Aug 9, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

t-hamano commented Aug 10, 2026

Uh oh!

github-actions Bot commented Aug 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

joedolson commented Aug 10, 2026

Uh oh!

joedolson left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

annezazu commented Aug 10, 2026

Uh oh!

joedolson commented Aug 10, 2026

Uh oh!

t-hamano commented Aug 11, 2026

Uh oh!

fcoveram commented Aug 11, 2026

Uh oh!

tyxla commented Aug 11, 2026

Uh oh!

jasmussen commented Aug 11, 2026

Uh oh!

t-hamano commented Aug 11, 2026

Uh oh!

tyxla left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

t-hamano commented Aug 7, 2026 •

edited

Loading

github-actions Bot commented Aug 10, 2026 •

edited

Loading

t-hamano commented Aug 11, 2026 •

edited

Loading