WordPress · oandregal · Jul 21, 2025 · Jul 17, 2025 · Jul 17, 2025 · Jul 17, 2025
@@ -207,6 +207,7 @@ Properties:
 -   `showMedia`: Whether the media should be shown in the UI. `true` by default.
 -   `showDescription`: Whether the description should be shown in the UI. `true` by default.
 -   `showLevels`: Whether to display the hierarchical levels for the data. `false` by default. See related `getItemLevel` DataView prop.
+-   `groupByField`: The id of the field used for grouping the dataset. So far, only the `grid` layout supports grouping.
 -   `fields`: a list of remaining field `id` that are visible in the UI and the specific order in which they are displayed.
 -   `layout`: config that is specific to a particular layout type.
 

@@ -326,3 +326,40 @@ export const CustomPerPageSizes = () => {
 		/>
 	);
 };
+
+export const GroupedGridLayout = () => {
+	const [ view, setView ] = useState< View >( {
+		type: LAYOUT_GRID,
+		search: '',
+		page: 1,
+		perPage: 20,
+		filters: [],
+		fields: [ 'satellites' ],
+		titleField: 'title',
+		descriptionField: 'description',
+		mediaField: 'image',
+		groupByField: 'type',
+		layout: {
+			badgeFields: [ 'satellites' ],
+		},
+	} );
+	const { data: shownData, paginationInfo } = useMemo( () => {
+		return filterSortAndPaginate( data, view, fields );
+	}, [ view ] );
+	return (
+		<DataViews
+			getItemId={ ( item ) => item.id.toString() }
+			paginationInfo={ paginationInfo }
+			data={ shownData }
+			view={ view }
+			fields={ fields }
+			onChangeView={ setView }
+			actions={ actions }
+			defaultLayouts={ {
+				[ LAYOUT_GRID ]: {},
+				[ LAYOUT_LIST ]: {},
+				[ LAYOUT_TABLE ]: {},
+			} }
+		/>
+	);
+};
@@ -16,7 +16,7 @@ import {
 	FlexItem,
 	privateApis as componentsPrivateApis,
 } from '@wordpress/components';
-import { __ } from '@wordpress/i18n';
+import { __, sprintf } from '@wordpress/i18n';
 import { useInstanceId } from '@wordpress/compose';
 
 /**
@@ -293,51 +293,142 @@ function ViewGrid< Item >( {
 				gridTemplateColumns: `repeat(${ usedPreviewSize }, minmax(0, 1fr))`,
 		  }
 		: {};
+
+	const groupField = view.groupByField
+		? fields.find( ( f ) => f.id === view.groupByField )
+		: null;
+
+	// Group data by groupByField if specified
+	const dataByGroup = groupField
+		? data.reduce( ( groups: { [ key: string ]: typeof data }, item ) => {
+				const groupName = groupField.getValue( { item } );
+				if ( ! groups[ groupName ] ) {
+					groups[ groupName ] = [];
+				}
+				groups[ groupName ].push( item );
+				return groups;
+		  }, {} )
+		: null;
+
 	return (
 		<>
-			{ hasData && (
-				<Grid
-					gap={ 8 }
-					columns={ 2 }
-					alignment="top"
-					className={ clsx( 'dataviews-view-grid', className ) }
-					style={ gridStyle }
-					aria-busy={ isLoading }
-				>
-					{ data.map( ( item ) => {
-						return (
-							<GridItem
-								key={ getItemId( item ) }
-								view={ view }
-								selection={ selection }
-								onChangeSelection={ onChangeSelection }
-								onClickItem={ onClickItem }
-								isItemClickable={ isItemClickable }
-								renderItemLink={ renderItemLink }
-								getItemId={ getItemId }
-								item={ item }
-								actions={ actions }
-								mediaField={ mediaField }
-								titleField={ titleField }
-								descriptionField={ descriptionField }
-								regularFields={ regularFields }
-								badgeFields={ badgeFields }
-								hasBulkActions={ hasBulkActions }
-							/>
-						);
-					} ) }
-				</Grid>
-			) }
-			{ ! hasData && (
-				<div
-					className={ clsx( {
-						'dataviews-loading': isLoading,
-						'dataviews-no-results': ! isLoading,
-					} ) }
-				>
-					<p>{ isLoading ? <Spinner /> : __( 'No results' ) }</p>
-				</div>
-			) }
+			{
+				// Render multiple groups.
+				hasData && groupField && dataByGroup && (
+					<VStack spacing={ 4 }>
+						{ Object.entries( dataByGroup ).map(
+							( [ groupName, groupItems ] ) => (
+								<VStack key={ groupName } spacing={ 2 }>
+									<h3 className="dataviews-view-grid__group-header">
+										{ sprintf(
+											// translators: 1: The label of the field e.g. "Date". 2: The value of the field, e.g.: "May 2022".
+											__( '%1$s: %2$s' ),
+											groupField.label,
+											groupName
+										) }
+									</h3>
+									<Grid
+										gap={ 8 }
+										columns={ 2 }
+										alignment="top"
+										className={ clsx(
+											'dataviews-view-grid',
+											className
+										) }
+										style={ gridStyle }
+										aria-busy={ isLoading }
+									>
+										{ groupItems.map( ( item ) => {
+											return (
+												<GridItem
+													key={ getItemId( item ) }
+													view={ view }
+													selection={ selection }
+													onChangeSelection={
+														onChangeSelection
+													}
+													onClickItem={ onClickItem }
+													isItemClickable={
+														isItemClickable
+													}
+													renderItemLink={
+														renderItemLink
+													}
+													getItemId={ getItemId }
+													item={ item }
+													actions={ actions }
+													mediaField={ mediaField }
+													titleField={ titleField }
+													descriptionField={
+														descriptionField
+													}
+													regularFields={
+														regularFields
+													}
+													badgeFields={ badgeFields }
+													hasBulkActions={
+														hasBulkActions
+													}
+												/>
+											);
+										} ) }
+									</Grid>
+								</VStack>
+							)
+						) }
+					</VStack>
+				)
+			}
+
+			{
+				// Render a single grid with all data.
+				hasData && ! dataByGroup && (
+					<Grid
+						gap={ 8 }
+						columns={ 2 }
+						alignment="top"
+						className={ clsx( 'dataviews-view-grid', className ) }
+						style={ gridStyle }
+						aria-busy={ isLoading }
+					>
+						{ data.map( ( item ) => {
+							return (
+								<GridItem
+									key={ getItemId( item ) }
+									view={ view }
+									selection={ selection }
+									onChangeSelection={ onChangeSelection }
+									onClickItem={ onClickItem }
+									isItemClickable={ isItemClickable }
+									renderItemLink={ renderItemLink }
+									getItemId={ getItemId }
+									item={ item }
+									actions={ actions }
+									mediaField={ mediaField }
+									titleField={ titleField }
+									descriptionField={ descriptionField }
+									regularFields={ regularFields }
+									badgeFields={ badgeFields }
+									hasBulkActions={ hasBulkActions }
+								/>
+							);
+						} ) }
+					</Grid>
+				)
+			}
+			{
+				// Render empty state.
+				! hasData && (
+					<div
+						className={ clsx( {
+							'dataviews-loading': isLoading,
+							'dataviews-no-results': ! isLoading,
+						} ) }
+					>
+						<p>{ isLoading ? <Spinner /> : __( 'No results' ) }</p>
+					</div>
+				)
+			}
 		</>
 	);
 }

@@ -166,3 +166,11 @@
 .dataviews-view-grid__media--clickable {
 	cursor: pointer;
 }
+
+.dataviews-view-grid__group-header {
+	font-size: 16px;
+	font-weight: 600;
+	color: $gray-900;
+	margin: 0 0 $grid-unit-10 0;
+	padding: 0 $grid-unit-60;
+}
@@ -375,16 +375,32 @@ export function filterSortAndPaginate< Item >(
 	}
 
 	// Handle sorting.
-	if ( view.sort ) {
-		const fieldId = view.sort.field;
-		const fieldToSort = _fields.find( ( field ) => {
-			return field.id === fieldId;
-		} );
-		if ( fieldToSort ) {
-			filteredData.sort( ( a, b ) => {
-				return fieldToSort.sort( a, b, view.sort?.direction ?? 'desc' );
+	if ( view.sort || view.groupByField ) {
+		filteredData.sort( ( a, b ) => {
+			// Sort by the group by field.
+			const groupByField = _fields.find( ( field ) => {
+				return field.id === view.groupByField;
 			} );
-		}
+			if ( view.groupByField && groupByField ) {
+				const groupCompare = groupByField.sort( a, b, 'asc' );
+
+				// If items are in different groups, return the group comparison result.
+				// Otherwise, fall back to sorting by the sort field.
+				if ( groupCompare !== 0 ) {
+					return groupCompare;
+				}
+			}
+
+			// Sort by the sort field.
+			const sortByField = _fields.find( ( field ) => {
+				return field.id === view?.sort?.field;
+			} );
+			if ( view.sort && sortByField ) {
+				return sortByField.sort( a, b, view.sort?.direction ?? 'desc' );
+			}
+
+			return 0;
+		} );
 	}
 
 	// Handle pagination.

@@ -748,6 +748,45 @@
 } );
 
 describe( 'sorting', () => {
+	it( 'should sort by groupByField first, then by sort.field', () => {
+		const { data: result } = filterSortAndPaginate(
+			data,
+			{
+				sort: { field: 'title', direction: 'desc' },
+				groupByField: 'type',
+			},
+			fields
+		);
+
+		expect( result ).toHaveLength( 11 );
+
+		expect( result[ 0 ].type ).toBe( 'Gas giant' );
+		expect( result[ 0 ].title ).toBe( 'Saturn' );
+		expect( result[ 1 ].type ).toBe( 'Gas giant' );
+		expect( result[ 1 ].title ).toBe( 'Jupiter' );
+
+		expect( result[ 2 ].type ).toBe( 'Ice giant' );
+		expect( result[ 2 ].title ).toBe( 'Uranus' );
+		expect( result[ 3 ].type ).toBe( 'Ice giant' );
+		expect( result[ 3 ].title ).toBe( 'Neptune' );
+
+		expect( result[ 4 ].type ).toBe( 'Not a planet' );
+		expect( result[ 4 ].title ).toBe( 'Space' );
+		expect( result[ 5 ].type ).toBe( 'Not a planet' );
+		expect( result[ 5 ].title ).toBe( 'NASA' );
+		expect( result[ 6 ].type ).toBe( 'Not a planet' );
+		expect( result[ 6 ].title ).toBe( 'Apollo' );
+
+		expect( result[ 7 ].type ).toBe( 'Terrestrial' );
+		expect( result[ 7 ].title ).toBe( 'Venus' );
+		expect( result[ 8 ].type ).toBe( 'Terrestrial' );
+		expect( result[ 8 ].title ).toBe( 'Mercury' );
+		expect( result[ 9 ].type ).toBe( 'Terrestrial' );
+		expect( result[ 9 ].title ).toBe( 'Mars' );
+		expect( result[ 10 ].type ).toBe( 'Terrestrial' );
+		expect( result[ 10 ].title ).toBe( 'Earth' );
+	} );
+
 	it( 'should sort integer field types', () => {
 		const { data: result } = filterSortAndPaginate(
 			data,
@@ -853,6 +892,28 @@
 		expect( result[ 0 ].title ).toBe( 'Uranus' );
 		expect( result[ 1 ].title ).toBe( 'Neptune' );
 	} );
+
+	it( 'should sort only by groupByField when sort is not specified', () => {
+		const { data: result } = filterSortAndPaginate(
+			data,
+			{
+				groupByField: 'type',
+			},
+			fields
+		);
+
+		let currentType = result[ 0 ].type;
+		let groupCount = 1;
+
+		for ( let i = 1; i < result.length; i++ ) {
+			if ( result[ i ].type !== currentType ) {
+				currentType = result[ i ].type;
+				groupCount++;
+			}
+		}
+
+		expect( groupCount ).toBe( 4 );
+	} );
 } );
 
 describe( 'pagination', () => {

@@ -419,6 +419,11 @@ interface ViewBase {
 	 * Whether to show the hierarchical levels.
 	 */
 	showLevels?: boolean;
+
+	/**
+	 * The field to group by.
+	 */
+	groupByField?: string;
 }
 
 export interface ColumnStyle {