Skip to content

Administration: Add box reordering toggle to Screen Options. #12180

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
poligilad-auto wants to merge 2 commits into
base: trunk
Choose a base branch
from
Open

Administration: Add box reordering toggle to Screen Options. #12180

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
170cc4a
Administration: Add box reordering toggle to Screen Options.
poligilad-auto Jun 15, 2026
ec888cf
Merge branch 'trunk' into poligilad-auto/metabox-reordering-toggle
joedolson Jul 7, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions src/js/_enqueues/admin/common.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1859,6 +1859,7 @@ $( function() {
var width = navigator.userAgent.indexOf('AppleWebKit/') > -1 ? $window.width() : window.innerWidth;

if (
$body.hasClass( 'meta-box-reordering-disabled' ) ||
( width <= 782 ) ||
( 1 >= $sortables.find( '.ui-sortable-handle:visible' ).length && jQuery( '.columns-prefs-1 input' ).prop( 'checked' ) )
) {
Expand Down
99 changes: 99 additions & 0 deletions src/js/_enqueues/admin/postbox.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -104,6 +104,10 @@
postboxWithinSortablesIndex = postboxesWithinSortables.index( postbox ),
firstOrLastPositionMessage;

if ( ! postboxes.metaBoxReorderingEnabled ) {
return;
}

if ( 'dashboard_browser_nag' === postboxId ) {
return;
}
Expand Down Expand Up @@ -344,6 +348,13 @@
postboxes.save_order( page );
}
});

$( '.meta-box-reordering-toggle' ).on( 'click.postboxes', function() {
var enabled = $( this ).prop( 'checked' );

postboxes.setMetaBoxReordering( enabled );
postboxes.save_meta_box_reordering_state( enabled );
} );
},

/**
Expand Down Expand Up @@ -419,6 +430,8 @@
}
});

this.setMetaBoxReordering( this.isMetaBoxReorderingEnabled() );

if ( isMobile ) {
$(document.body).on('orientationchange.postboxes', function(){ postboxes._pb_change(); });
this._pb_change();
Expand All @@ -437,6 +450,68 @@
});
},

/**
* Checks whether meta box reordering is enabled.
*
* @since 7.1.0
*
* @return {boolean} Whether meta box reordering is enabled.
*/
isMetaBoxReorderingEnabled: function() {
var $toggle = $( '#meta-box-reordering' );

if ( $toggle.length ) {
return $toggle.prop( 'checked' );
}

return ! $( document.body ).hasClass( 'meta-box-reordering-disabled' );
},

/**
* Enables or disables the meta box reordering UI.
*
* @since 7.1.0
*
* @param {boolean} enabled Whether reordering should be enabled.
* @return {void}
*/
setMetaBoxReordering: function( enabled ) {

@tyxla tyxla Jul 8, 2026

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 new checkbox lives inside #screen-options-wrap, so the existing $('#screen-options-wrap input').on('click', maybeDisableSortables) binding (in common.js) and the .meta-box-reordering-toggle handler both fire on the same click, and setMetaBoxReordering() calls maybeDisableSortables() a third time. Sounds like it may need tidying up a bit.

var $body = $( document.body ),
$orderButtons = $( '.postbox .handle-order-higher, .postbox .handle-order-lower' );

this.metaBoxReorderingEnabled = !! enabled;

$body
.toggleClass( 'meta-box-reordering-enabled', this.metaBoxReorderingEnabled )

@joedolson joedolson Jul 7, 2026

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.

I think we can simplify this by not adding meta-box-reordering-enabled; this is the default state, and can be represented by the absence of the disabled class. (See above)

.toggleClass( 'meta-box-reordering-disabled', ! this.metaBoxReorderingEnabled );

if ( this.metaBoxReorderingEnabled ) {
$orderButtons
.prop( 'disabled', false )
.removeAttr( 'tabindex aria-hidden' );
this.updateOrderButtonsProperties();
} else {
$orderButtons
.prop( 'disabled', true )
.attr( {
'aria-hidden': 'true',

@joedolson joedolson Jul 7, 2026

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.

It's not necessary to add any of these attributes to items hidden using display: none. The display attribute already removes them from the DOM.

@joedolson joedolson Jul 7, 2026

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.

(that covers all of disabled, aria-hidden, and tabindex; these changes can all be removed.)

tabindex: '-1'
} );
}

if ( window.wpResponsive && window.wpResponsive.maybeDisableSortables ) {
window.wpResponsive.maybeDisableSortables();
return;
}

try {
$( '.meta-box-sortables' )
.sortable( this.metaBoxReorderingEnabled ? 'enable' : 'disable' )
.find( '.ui-sortable-handle' )
.toggleClass( 'is-non-sortable', ! this.metaBoxReorderingEnabled );
Comment on lines +508 to +511

@tyxla tyxla Jul 8, 2026

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.

Why is this in a try/catch block? Is the intent to guard against calling .sortable() before init? If yes, a better way to do this would be to just either do if ( $.fn.sortable ) or .hasClass( 'ui-sortable' ).

} catch ( e ) {}
},

/**
* Saves the state of the postboxes to the server.
*
Expand Down Expand Up @@ -476,6 +551,30 @@
);
},

/**
* Saves the meta box reordering setting to the server.
*
* @since 7.1.0
*
* @memberof postboxes
*
* @param {boolean} enabled Whether meta box reordering is enabled.
* @return {void}
*/
save_meta_box_reordering_state : function( enabled ) {
$.post(
ajaxurl,
{
action: 'meta-box-reordering',
enabled: enabled ? 1 : 0,
screenoptionnonce: $( '#screenoptionnonce' ).val()
},
function() {
wp.a11y.speak( __( 'Screen Options updated.' ) );
}
);
},

/**
* Saves the order of the postboxes to the server.
*
Expand Down
1 change: 1 addition & 0 deletions src/wp-admin/admin-ajax.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -79,6 +79,7 @@
'add-user',
'closed-postboxes',
'hidden-columns',
'meta-box-reordering',
'update-welcome-panel',
'menu-get-metabox',
'wp-link-ajax',
Expand Down
2 changes: 2 additions & 0 deletions src/wp-admin/admin-header.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -214,6 +214,8 @@
$admin_body_class .= ' block-editor-page wp-embed-responsive';
}

$admin_body_class .= wp_is_meta_box_reordering_enabled() ? ' meta-box-reordering-enabled' : ' meta-box-reordering-disabled';

@joedolson joedolson Jul 7, 2026

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.

I think we can simplify this by not adding meta-box-reordering-enabled; this is the default state, and can be represented by the absence of the disabled class.


$admin_body_class .= ' wp-theme-' . sanitize_html_class( get_template() );
if ( is_child_theme() ) {
$admin_body_class .= ' wp-child-theme-' . sanitize_html_class( get_stylesheet() );
Expand Down
17 changes: 17 additions & 0 deletions src/wp-admin/css/common.css
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1959,6 +1959,18 @@ p.auto-update-status {
line-height: 2.35;
}

.metabox-prefs > p {
margin: 0 0 8px;
}

.additional-settings-prefs {
margin-top: 14px;
}

.additional-settings-prefs legend {
padding-bottom: 2px;
}

#number-of-columns {
display: inline-block;
vertical-align: middle;
Expand Down Expand Up @@ -2256,6 +2268,11 @@ html.wp-toolbar {
width: 1.62rem;
}

.js.meta-box-reordering-disabled .postbox .handle-order-higher,
.js.meta-box-reordering-disabled .postbox .handle-order-lower {
display: none;
}

/* Post box order buttons in the block editor meta boxes area. */
.edit-post-meta-boxes-area .postbox .handle-order-higher,
.edit-post-meta-boxes-area .postbox .handle-order-lower {
Expand Down
4 changes: 4 additions & 0 deletions src/wp-admin/css/dashboard.css
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1385,6 +1385,10 @@ a.rsswidget {
}
}

.js.meta-box-reordering-disabled #dashboard-widgets .postbox-container .empty-container {
display: none;
}

@media screen and (max-width: 870px) {
/* @deprecated 5.9.0 -- Lists removed from welcome panel. */
.welcome-panel .welcome-panel-column li {
Expand Down
19 changes: 19 additions & 0 deletions src/wp-admin/includes/ajax-actions.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1856,6 +1856,25 @@ function wp_ajax_hidden_columns() {
wp_die( 1 );
}

/**
* Handles the meta box reordering setting via Ajax.
*
* @since 7.1.0
*/
function wp_ajax_meta_box_reordering() {
check_ajax_referer( 'screen-options-nonce', 'screenoptionnonce' );

$user = wp_get_current_user();
if ( ! $user ) {
wp_die( -1 );
}
Comment on lines +1868 to +1870

@tyxla tyxla Jul 8, 2026

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.

This will never happen, I believe - $user will always return a WP_User object that evaluates to true.

Perhaps we meant to do either $user->exists() or is_user_logged_in().


$enabled = isset( $_POST['enabled'] ) && '1' === (string) $_POST['enabled'];
update_user_meta( $user->ID, 'meta_box_reordering', $enabled ? 'enabled' : 'disabled' );

@tyxla tyxla Jul 8, 2026

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.

We seem to be using both the user option and user meta APIs a bit asymetrically here. This will work just because get_user_option falls back to the unprefixed key, but this feels unintended to me. Maybe we should just use the update_user_option API instead?


wp_die( 1 );
}

/**
* Handles updating whether to display the welcome panel via AJAX.
*
Expand Down
73 changes: 66 additions & 7 deletions src/wp-admin/includes/class-wp-screen.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1006,11 +1006,23 @@ public function show_screen_options() {

$this->_screen_settings = '';

$additional_settings = '';

if ( $this->show_meta_box_reordering_options() ) {
Comment on lines +1009 to +1011

@tyxla tyxla Jul 8, 2026

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.

If this is false (when no meta boxes are registered), we'll renter an an "Additional settings" fieldset that contains only a legend and a hidden label - a visible but empty section.

$additional_settings .= $this->get_meta_box_reordering_option();
}

if ( 'post' === $this->base ) {
$expand = '<fieldset class="editor-expand hidden"><legend>' . __( 'Additional settings' ) . '</legend><label for="editor-expand-toggle">';
$expand .= '<input type="checkbox" id="editor-expand-toggle"' . checked( get_user_setting( 'editor_expand', 'on' ), 'on', false ) . ' />';
$expand .= __( 'Enable full-height editor and distraction-free functionality.' ) . '</label></fieldset>';
$this->_screen_settings = $expand;
$additional_settings .= '<label class="editor-expand hidden" for="editor-expand-toggle">';
$additional_settings .= '<input type="checkbox" id="editor-expand-toggle"' . checked( get_user_setting( 'editor_expand', 'on' ), 'on', false ) . ' /> ';
$additional_settings .= __( 'Enable full-height editor and distraction-free functionality.' ) . '</label>';
}

if ( $additional_settings ) {
$this->_screen_settings = '<fieldset class="metabox-prefs additional-settings-prefs">';
$this->_screen_settings .= '<legend>' . __( 'Additional settings' ) . '</legend>';
$this->_screen_settings .= $additional_settings;
$this->_screen_settings .= '</fieldset>';
}

/**
Expand All @@ -1023,7 +1035,7 @@ public function show_screen_options() {
*/
$this->_screen_settings = apply_filters( 'screen_settings', $this->_screen_settings, $this );

if ( $this->_screen_settings || $this->_options ) {
if ( $this->_screen_settings || $this->_options || $this->show_meta_box_reordering_options() ) {
$show_screen = true;
}

Expand Down Expand Up @@ -1120,8 +1132,8 @@ public function render_meta_boxes_preferences() {
<fieldset class="metabox-prefs">
<legend><?php _e( 'Screen elements' ); ?></legend>
<p>
<?php _e( 'Some screen elements can be shown or hidden by using the checkboxes.' ); ?>
<?php _e( 'Expand or collapse the elements by clicking on their headings, and arrange them by dragging their headings or by clicking on the up and down arrows.' ); ?>
<?php _e( 'Use the checkboxes to show or hide screen elements.' ); ?>

@joedolson joedolson Jul 7, 2026

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.

Let's not change strings that aren't necessary to change as part of this issue.

<?php _e( 'Expand or collapse screen elements by clicking their headings.' ); ?>

@joedolson joedolson Jul 7, 2026

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.

This text should still address the ability to move metaboxes, but add text covering how to turn the option on and off.

</p>
<div class="metabox-prefs-container">
<?php
Expand All @@ -1148,6 +1160,53 @@ public function render_meta_boxes_preferences() {
<?php
}

/**
* Renders the option to enable or disable meta box reordering.
*
* @since 7.1.0
*/
public function render_meta_box_reordering_options() {

@tyxla tyxla Jul 8, 2026

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.

This seems to be dead/unused now. Along with the corresponding test.

if ( ! $this->show_meta_box_reordering_options() ) {
return;
}

?>
<fieldset class="metabox-prefs additional-settings-prefs">
<legend><?php _e( 'Additional settings' ); ?></legend>
<?php echo $this->get_meta_box_reordering_option(); ?>
</fieldset>
<?php
}

/**
* Gets the option to enable or disable meta box reordering.
*
* @since 7.1.0
*
* @return string Meta box reordering option markup.
*/
private function get_meta_box_reordering_option() {
return '<label for="meta-box-reordering">'
. '<input class="meta-box-reordering-toggle" name="meta-box-reordering" type="checkbox" id="meta-box-reordering" value="enabled" ' . checked( wp_is_meta_box_reordering_enabled(), true, false ) . ' /> '
. __( 'Enable box reordering' )
. '</label>';
}

/**
* Determines whether to show the meta box reordering option.
*
* @since 7.1.0
*
* @global array $wp_meta_boxes Global meta box state.
*
* @return bool Whether to show the option.
*/
private function show_meta_box_reordering_options() {
global $wp_meta_boxes;

return ! empty( $wp_meta_boxes[ $this->id ] );
}

/**
* Renders the list table columns preferences.
*
Expand Down
13 changes: 13 additions & 0 deletions src/wp-admin/includes/screen.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -194,6 +194,19 @@ function get_hidden_meta_boxes( $screen ) {
return apply_filters( 'hidden_meta_boxes', $hidden, $screen, $use_defaults );
}

/**
* Determines whether meta box reordering is enabled.
*
* @since 7.1.0
*
* @return bool Whether meta box reordering is enabled.
*/
function wp_is_meta_box_reordering_enabled() {
$setting = get_user_option( 'meta_box_reordering' );

return false === $setting ? true : 'disabled' !== $setting;
}

/**
* Register and configure an admin screen option
*
Expand Down
1 change: 1 addition & 0 deletions tests/phpunit/includes/testcase-ajax.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -66,6 +66,7 @@ abstract class WP_Ajax_UnitTestCase extends WP_UnitTestCase {
'add-user',
'closed-postboxes',
'hidden-columns',
'meta-box-reordering',
'update-welcome-panel',
'menu-get-metabox',
'wp-link-ajax',
Expand Down
35 changes: 35 additions & 0 deletions tests/phpunit/tests/admin/includesScreen.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -260,6 +260,41 @@ public function test_taxonomy_with_special_suffix_as_hookname() {
$this->assertFalse( $screen->is_block_editor );
}

public function test_meta_box_reordering_enabled_defaults_to_true() {
wp_set_current_user( self::factory()->user->create( array( 'role' => 'administrator' ) ) );

$this->assertTrue( wp_is_meta_box_reordering_enabled() );
}

public function test_meta_box_reordering_enabled_respects_user_option() {
$user_id = self::factory()->user->create( array( 'role' => 'administrator' ) );
wp_set_current_user( $user_id );
update_user_meta( $user_id, 'meta_box_reordering', 'disabled' );

$this->assertFalse( wp_is_meta_box_reordering_enabled() );
}

public function test_meta_box_reordering_option_is_rendered_for_screens_with_meta_boxes() {
global $wp_meta_boxes;

$old_wp_meta_boxes = $wp_meta_boxes;
$screen = convert_to_screen( 'dashboard' );

add_meta_box( 'testbox1', 'Test Metabox', '__return_false', $screen );

try {
ob_start();
$screen->render_meta_box_reordering_options();
$output = ob_get_clean();
} finally {
$wp_meta_boxes = $old_wp_meta_boxes;
}

$this->assertStringContainsString( 'id="meta-box-reordering"', $output );
$this->assertStringContainsString( 'Additional settings', $output );
$this->assertStringContainsString( 'Enable box reordering', $output );
}

public function test_post_type_with_edit_prefix() {
register_post_type( 'edit-some-thing' );
$screen = convert_to_screen( 'edit-some-thing' );
Expand Down
Loading
Loading