Query Loop: Add 'menu_order' as sorting option

packages/block-library/CHANGELOG.md

@@ -2,6 +2,10 @@
 
 ## Unreleased
 
+### Enhancements
+
+-   Query Loop Block: Enable custom order or `menu_order` ordering option for post types that support it. ([#68781](https://github.com/WordPress/gutenberg/pull/68781))
+
 ## 9.19.0 (2025-02-28)
 
 ## 9.18.0 (2025-02-12)

packages/block-library/src/query/edit/inspector-controls/index.js

@@ -35,6 +35,7 @@ import {
 	useAllowedControls,
 	isControlAllowed,
 	useTaxonomies,
+	useOrderByOptions,
 } from '../../utils';
 import { useToolsPanelDropdownMenuProps } from '../../../utils/hooks';
 
@@ -111,6 +112,7 @@ export default function QueryInspectorControls( props ) {
 		return onChangeDebounced.cancel;
 	}, [ querySearch, onChangeDebounced ] );
 
+	const orderByOptions = useOrderByOptions( postType );
 	const showInheritControl =
 		! isSingular && isControlAllowed( allowedControls, 'inherit' );
 	const showPostTypeControl =
@@ -329,7 +331,7 @@ export default function QueryInspectorControls( props ) {
 							isShownByDefault
 						>
 							<OrderControl
-								{ ...{ order, orderBy } }
+								{ ...{ order, orderBy, orderByOptions } }
 								onChange={ setQuery }
 							/>
 						</ToolsPanelItem>

packages/block-library/src/query/edit/inspector-controls/order-control.js

@@ -4,7 +4,7 @@
 import { SelectControl } from '@wordpress/components';
 import { __ } from '@wordpress/i18n';
 
-const orderOptions = [
+const defaultOrderByOptions = [
 	{
 		label: __( 'Newest to oldest' ),
 		value: 'date/desc',
@@ -24,14 +24,20 @@ const orderOptions = [
 		value: 'title/desc',
 	},
 ];
-function OrderControl( { order, orderBy, onChange } ) {
+
+function OrderControl( {
+	order,
+	orderBy,
+	orderByOptions = defaultOrderByOptions,
+	onChange,
+} ) {
 	return (
 		<SelectControl
 			__nextHasNoMarginBottom
 			__next40pxDefaultSize
 			label={ __( 'Order by' ) }
 			value={ `${ orderBy }/${ order }` }
-			options={ orderOptions }
+			options={ orderByOptions }
 			onChange={ ( value ) => {
 				const [ newOrderBy, newOrder ] = value.split( '/' );
 				onChange( { order: newOrder, orderBy: newOrderBy } );

packages/block-library/src/query/utils.js

@@ -6,13 +6,15 @@ import { useMemo } from '@wordpress/element';
 import { store as coreStore } from '@wordpress/core-data';
 import { store as blockEditorStore } from '@wordpress/block-editor';
 import { decodeEntities } from '@wordpress/html-entities';
+import { __ } from '@wordpress/i18n';
 import {
 	cloneBlock,
 	getBlockSupport,
 	store as blocksStore,
 } from '@wordpress/blocks';
 
 /** @typedef {import('@wordpress/blocks').WPBlockVariation} WPBlockVariation */
+/** @typedef {import('@wordpress/components/build-types/query-controls/types').OrderByOption} OrderByOption */
 
 /**
  * @typedef IHasNameAndId
@@ -186,6 +188,62 @@ export function useIsPostTypeHierarchical( postType ) {
 	);
 }
 
+/**
+ * List of avaiable options to order by.
+ *
+ * @param {string} postType The post type to check.
+ * @return {OrderByOption[]} List of order options.
+ */
+export function useOrderByOptions( postType ) {
+	const supportsCustomOrder = useSelect(
+		( select ) => {
+			const type = select( coreStore ).getPostType( postType );
+			return !! type?.supports?.[ 'page-attributes' ];
+		},
+		[ postType ]
+	);
+
+	return useMemo( () => {
+		const orderByOptions = [
+			{
+				label: __( 'Newest to oldest' ),
+				value: 'date/desc',
+			},
+			{
+				label: __( 'Oldest to newest' ),
+				value: 'date/asc',
+			},
+			{
+				/* translators: Label for ordering posts by title in ascending order. */
+				label: __( 'A → Z' ),
+				value: 'title/asc',
+			},
+			{
+				/* translators: Label for ordering posts by title in descending order. */
+				label: __( 'Z → A' ),
+				value: 'title/desc',
+			},
+		];
+
+		if ( supportsCustomOrder ) {
+			orderByOptions.push(
+				{
+					/* translators: Label for ordering posts by ascending menu order. */
+					label: __( 'Ascending by order' ),
+					value: 'menu_order/asc',
+				},
+				{
+					/* translators: Label for ordering posts by descending menu order. */
+					label: __( 'Descending by order' ),
+					value: 'menu_order/desc',
+				}
+			);
+		}
+
+		return orderByOptions;
+	}, [ supportsCustomOrder ] );
+}
+
 /**
  * Hook that returns the query properties' names defined by the active
  * block variation, to determine which block's filters to show.

packages/components/CHANGELOG.md

@@ -2,6 +2,10 @@
 
 ## Unreleased
 
+### Enhancement
+
+-   `QueryControls`: Add menu_order sorting option if supported by the post type. ([#68781](https://github.com/WordPress/gutenberg/pull/68781)).
+
 ## 29.5.0 (2025-02-28)
 
 ### Documentation

packages/components/src/query-controls/README.md

@@ -36,7 +36,7 @@ const QUERY_DEFAULTS = {
 
 const MyQueryControls = () => {
 	const [ query, setQuery ] = useState( QUERY_DEFAULTS );
-	const { category, categories, maxItems, minItems, numberOfItems, order, orderBy  } = query;
+	const { category, categories, maxItems, minItems, numberOfItems, order, orderBy } = query;
 
 	const updateQuery = ( newQuery ) => {
 		setQuery( { ...query, ...newQuery } );
@@ -213,7 +213,14 @@ The order in which to retrieve posts.
 -   Required: No
 -   Platform: Web
 
-#### `orderBy`: `'date' | 'title'`
+#### `orderBy`: `'date' | 'title' | 'menu_order'`
+
+The meta key by which to order posts.
+
+-   Required: No
+-   Platform: Web
+
+#### `orderByOptions`: `OrderByOption[]`
 
 The meta key by which to order posts.
 
@@ -246,4 +253,4 @@ The selected category for the `categoriesList` prop.
 Start opting into the larger default height that will become the default size in a future version.
 
 - Required: No
-- Default: `false`
+- Default: `false`

packages/components/src/query-controls/index.native.js

@@ -14,7 +14,7 @@ import CategorySelect from './category-select';
 const DEFAULT_MIN_ITEMS = 1;
 const DEFAULT_MAX_ITEMS = 100;
 
-const options = [
+const defaultOrderByOptions = [
 	{
 		label: __( 'Newest to oldest' ),
 		value: 'date/desc',
@@ -42,6 +42,7 @@ const QueryControls = memo(
 		numberOfItems,
 		order,
 		orderBy,
+		orderByOptions = defaultOrderByOptions,
 		maxItems = DEFAULT_MAX_ITEMS,
 		minItems = DEFAULT_MIN_ITEMS,
 		onCategoryChange,
@@ -68,7 +69,7 @@ const QueryControls = memo(
 					<SelectControl
 						label={ __( 'Order by' ) }
 						value={ `${ orderBy }/${ order }` }
-						options={ options }
+						options={ orderByOptions }
 						onChange={ onChange }
 						hideCancelButton
 					/>

packages/components/src/query-controls/index.tsx

@@ -16,6 +16,7 @@ import type {
 	QueryControlsProps,
 	QueryControlsWithMultipleCategorySelectionProps,
 	QueryControlsWithSingleCategorySelectionProps,
+	OrderByOption,
 } from './types';
 
 const DEFAULT_MIN_ITEMS = 1;
@@ -34,13 +35,34 @@ function isMultipleCategorySelection(
 	return 'categorySuggestions' in props;
 }
 
+const defaultOrderByOptions: OrderByOption[] = [
+	{
+		label: __( 'Newest to oldest' ),
+		value: 'date/desc',
+	},
+	{
+		label: __( 'Oldest to newest' ),
+		value: 'date/asc',
+	},
+	{
+		/* translators: Label for ordering posts by title in ascending order. */
+		label: __( 'A → Z' ),
+		value: 'title/asc',
+	},
+	{
+		/* translators: Label for ordering posts by title in descending order. */
+		label: __( 'Z → A' ),
+		value: 'title/desc',
+	},
+];
+
 /**
  * Controls to query for posts.
  *
  * ```jsx
  * const MyQueryControls = () => (
  *   <QueryControls
- *     { ...{ maxItems, minItems, numberOfItems, order, orderBy } }
+ *     { ...{ maxItems, minItems, numberOfItems, order, orderBy, orderByOptions } }
  *     onOrderByChange={ ( newOrderBy ) => {
  *       updateQuery( { orderBy: newOrderBy } )
  *     }
@@ -65,6 +87,7 @@ export function QueryControls( {
 	numberOfItems,
 	order,
 	orderBy,
+	orderByOptions = defaultOrderByOptions,
 	maxItems = DEFAULT_MAX_ITEMS,
 	minItems = DEFAULT_MIN_ITEMS,
 	onAuthorChange,
@@ -89,26 +112,7 @@ export function QueryControls( {
 								? undefined
 								: `${ orderBy }/${ order }`
 						}
-						options={ [
-							{
-								label: __( 'Newest to oldest' ),
-								value: 'date/desc',
-							},
-							{
-								label: __( 'Oldest to newest' ),
-								value: 'date/asc',
-							},
-							{
-								/* translators: Label for ordering posts by title in ascending order. */
-								label: __( 'A → Z' ),
-								value: 'title/asc',
-							},
-							{
-								/* translators: Label for ordering posts by title in descending order. */
-								label: __( 'Z → A' ),
-								value: 'title/desc',
-							},
-						] }
+						options={ orderByOptions }
 						onChange={ ( value ) => {
 							if ( typeof value !== 'string' ) {
 								return;

packages/components/src/query-controls/types.ts

@@ -45,7 +45,18 @@ export type AuthorSelectProps = Pick<
 };
 
 type Order = 'asc' | 'desc';
-type OrderBy = 'date' | 'title';
+type OrderBy = 'date' | 'title' | 'menu_order';
+
+export type OrderByOption = {
+	/**
+	 * The label to be shown to the user.
+	 */
+	label: string;
+	/**
+	 * Option value passed to `onChange` when the option is selected.
+	 */
+	value: `${ OrderBy }/${ Order }`;
+};
 
 type BaseQueryControlsProps = {
 	/**
@@ -99,6 +110,10 @@ type BaseQueryControlsProps = {
 	 * The meta key by which to order posts.
 	 */
 	orderBy?: OrderBy;
+	/**
+	 * List of available ordering options.
+	 */
+	orderByOptions?: OrderByOption[];
 	/**
 	 * The selected author ID.
 	 */