feat: add groupBy support to query presets (#14808)

### What?

Adds `groupBy` field support to query presets. Presets now save, apply,
and clear groupBy state when switching between presets.

### Why?

Previously, `groupBy` settings would persist when switching between
presets. GroupBy was not being saved as part of the preset
configuration, so users couldn't save their preferred grouping with a
preset.

### How?

Added `groupBy?: string` to the `QueryPreset` type and updated the
preset collection config to include the field.

Modified `QueryPresetBar` to handle groupBy when selecting, deselecting,
resetting, saving, or creating presets.

Created custom Field and Cell components to display groupBy values in
the admin UI.

#### Preset creation with group-by added
<img width="711" height="684" alt="Screenshot 2025-12-03 at 3 15 03 PM"
src="https://github.com/user-attachments/assets/5fe6ee88-6ed7-40f6-b190-df6b2e89460c"
/>

#### Preset collection list view with group-by preset
<img width="2233" height="537" alt="Screenshot 2025-12-03 at 3 15 26 PM"
src="https://github.com/user-attachments/assets/a56645fc-9106-4885-8c54-0e000c429499"
/>

#### Preset creation without group-by
<img width="1250" height="704" alt="Screenshot 2025-12-03 at 3 15 48 PM"
src="https://github.com/user-attachments/assets/3438585b-7aa9-4336-9101-2fab59733480"
/>

Author: PatrikKozak

packages/payload/src/query-presets/config.ts

@@ -14,7 +14,7 @@ export const getQueryPresetsConfig = (config: Config): CollectionConfig => ({
   slug: queryPresetsCollectionSlug,
   access: getAccess(config),
   admin: {
-    defaultColumns: ['title', 'isShared', 'access', 'where', 'columns'],
+    defaultColumns: ['title', 'isShared', 'access', 'where', 'columns', 'groupBy'],
     hidden: true,
     useAsTitle: 'title',
   },
@@ -94,6 +94,17 @@ export const getQueryPresetsConfig = (config: Config): CollectionConfig => ({
         return true
       },
     },
+    {
+      name: 'groupBy',
+      type: 'text',
+      admin: {
+        components: {
+          Cell: '@payloadcms/ui#QueryPresetsGroupByCell',
+          Field: '@payloadcms/ui#QueryPresetsGroupByField',
+        },
+      },
+      label: 'Group By',
+    },
     {
       name: 'relatedCollection',
       type: 'select',

packages/payload/src/query-presets/types.ts

@@ -20,6 +20,7 @@ export type QueryPreset = {
     }
   }
   columns: CollectionPreferences['columns']
+  groupBy?: string
   id: number | string
   isShared: boolean
   relatedCollection: CollectionSlug

packages/ui/src/elements/QueryPresets/QueryPresetBar/index.tsx

@@ -83,6 +83,7 @@ export const QueryPresetBar: React.FC<{
       await refineListData(
         {
           columns: preset.columns ? transformColumnsToSearchParams(preset.columns) : undefined,
+          groupBy: preset.groupBy || '',
           preset: preset.id,
           where: preset.where,
         },
@@ -96,6 +97,7 @@ export const QueryPresetBar: React.FC<{
     await refineListData(
       {
         columns: [],
+        groupBy: '',
         preset: '',
         where: {},
       },
@@ -141,6 +143,7 @@ export const QueryPresetBar: React.FC<{
       await fetch(`${apiRoute}/payload-query-presets/${activePreset.id}`, {
         body: JSON.stringify({
           columns: transformColumnsToPreferences(query.columns),
+          groupBy: query.groupBy,
           where: query.where,
         }),
         credentials: 'include',
@@ -178,6 +181,7 @@ export const QueryPresetBar: React.FC<{
     apiRoute,
     activePreset?.id,
     query.columns,
+    query.groupBy,
     query.where,
     t,
     presetConfig?.labels?.singular,
@@ -216,6 +220,7 @@ export const QueryPresetBar: React.FC<{
                 await refineListData(
                   {
                     columns: transformColumnsToSearchParams(activePreset.columns),
+                    groupBy: activePreset.groupBy || '',
                     where: activePreset.where,
                   },
                   false,
@@ -263,6 +268,7 @@ export const QueryPresetBar: React.FC<{
       <CreateNewPresetDrawer
         initialData={{
           columns: transformColumnsToPreferences(query.columns),
+          groupBy: query.groupBy,
           relatedCollection: collectionSlug,
           where: query.where,
         }}

packages/ui/src/elements/QueryPresets/cells/GroupByCell/index.tsx

@@ -0,0 +1,63 @@
+import type { DefaultCellComponentProps } from 'payload'
+
+import { toWords } from 'payload/shared'
+import React, { useMemo } from 'react'
+
+import { useAuth } from '../../../../providers/Auth/index.js'
+import { useConfig } from '../../../../providers/Config/index.js'
+import { useTranslation } from '../../../../providers/Translation/index.js'
+import { reduceFieldsToOptions } from '../../../../utilities/reduceFieldsToOptions.js'
+
+export const QueryPresetsGroupByCell: React.FC<DefaultCellComponentProps> = ({
+  cellData,
+  rowData,
+}) => {
+  const { i18n } = useTranslation()
+  const { permissions } = useAuth()
+  const { config } = useConfig()
+
+  // Get the related collection from the row data
+  const relatedCollection = rowData?.relatedCollection as string
+
+  // Get the collection config for the related collection
+  const collectionConfig = useMemo(() => {
+    if (!relatedCollection) {
+      return null
+    }
+
+    return config.collections?.find((col) => col.slug === relatedCollection)
+  }, [relatedCollection, config.collections])
+
+  // Reduce fields to options to get proper labels
+  const reducedFields = useMemo(() => {
+    if (!collectionConfig) {
+      return []
+    }
+
+    const fieldPermissions = permissions?.collections?.[relatedCollection]?.fields
+
+    return reduceFieldsToOptions({
+      fieldPermissions,
+      fields: collectionConfig.fields,
+      i18n,
+    })
+  }, [collectionConfig, permissions, relatedCollection, i18n])
+
+  if (!cellData || typeof cellData !== 'string') {
+    return <div>No group by selected</div>
+  }
+
+  const isDescending = cellData.startsWith('-')
+  const fieldName = isDescending ? cellData.slice(1) : cellData
+  const direction = isDescending ? 'descending' : 'ascending'
+
+  // Find the field option to get the proper label
+  const fieldOption = reducedFields.find((field) => field.value === fieldName)
+  const displayLabel = fieldOption?.label || toWords(fieldName)
+
+  return (
+    <div>
+      {displayLabel} ({direction})
+    </div>
+  )
+}

packages/ui/src/elements/QueryPresets/fields/GroupByField/index.scss

@@ -0,0 +1,17 @@
+@import '../../../../scss/styles';
+
+@layer payload-default {
+  .query-preset-group-by-field {
+    .field-label {
+      margin-bottom: calc(var(--base) / 2);
+    }
+
+    .value-wrapper {
+      background-color: var(--theme-elevation-50);
+      padding: var(--base);
+      display: flex;
+      flex-wrap: wrap;
+      gap: calc(var(--base) / 2);
+    }
+  }
+}

packages/ui/src/elements/QueryPresets/fields/GroupByField/index.tsx

@@ -0,0 +1,78 @@
+'use client'
+import type { TextFieldClientComponent } from 'payload'
+
+import { toWords } from 'payload/shared'
+import React, { useMemo } from 'react'
+
+import { FieldLabel } from '../../../../fields/FieldLabel/index.js'
+import { useField } from '../../../../forms/useField/index.js'
+import { useAuth } from '../../../../providers/Auth/index.js'
+import { useConfig } from '../../../../providers/Config/index.js'
+import { useTranslation } from '../../../../providers/Translation/index.js'
+import { reduceFieldsToOptions } from '../../../../utilities/reduceFieldsToOptions.js'
+import { Pill } from '../../../Pill/index.js'
+import './index.scss'
+
+export const QueryPresetsGroupByField: TextFieldClientComponent = ({
+  field: { label, required },
+}) => {
+  const { path, value } = useField()
+  const { i18n } = useTranslation()
+  const { permissions } = useAuth()
+  const { config } = useConfig()
+
+  // Get the relatedCollection from the document data
+  const relatedCollectionField = useField({ path: 'relatedCollection' })
+  const relatedCollection = relatedCollectionField.value as string
+
+  // Get the collection config for the related collection
+  const collectionConfig = useMemo(() => {
+    if (!relatedCollection) {
+      return null
+    }
+
+    return config.collections?.find((col) => col.slug === relatedCollection)
+  }, [relatedCollection, config.collections])
+
+  // Reduce fields to options to get proper labels
+  const reducedFields = useMemo(() => {
+    if (!collectionConfig) {
+      return []
+    }
+
+    const fieldPermissions = permissions?.collections?.[relatedCollection]?.fields
+
+    return reduceFieldsToOptions({
+      fieldPermissions,
+      fields: collectionConfig.fields,
+      i18n,
+    })
+  }, [collectionConfig, permissions, relatedCollection, i18n])
+
+  const renderGroupBy = (groupByValue: string) => {
+    if (!groupByValue) {
+      return 'No group by selected'
+    }
+
+    const isDescending = groupByValue.startsWith('-')
+    const fieldName = isDescending ? groupByValue.slice(1) : groupByValue
+    const direction = isDescending ? 'descending' : 'ascending'
+
+    // Find the field option to get the proper label
+    const fieldOption = reducedFields.find((field) => field.value === fieldName)
+    const displayLabel = fieldOption?.label || toWords(fieldName)
+
+    return (
+      <Pill pillStyle="always-white" size="small">
+        <b>{displayLabel}</b> ({direction})
+      </Pill>
+    )
+  }
+
+  return (
+    <div className="field-type query-preset-group-by-field">
+      <FieldLabel as="h3" label={label} path={path} required={required} />
+      <div className="value-wrapper">{renderGroupBy(value as string)}</div>
+    </div>
+  )
+}

packages/ui/src/exports/client/index.ts

@@ -32,8 +32,10 @@ export { OrderableTable } from '../../elements/Table/OrderableTable.js'
 export { QueryPresetsColumnsCell } from '../../elements/QueryPresets/cells/ColumnsCell/index.js'
 export { QueryPresetsWhereCell } from '../../elements/QueryPresets/cells/WhereCell/index.js'
 export { QueryPresetsAccessCell } from '../../elements/QueryPresets/cells/AccessCell/index.js'
+export { QueryPresetsGroupByCell } from '../../elements/QueryPresets/cells/GroupByCell/index.js'
 export { QueryPresetsColumnField } from '../../elements/QueryPresets/fields/ColumnsField/index.js'
 export { QueryPresetsWhereField } from '../../elements/QueryPresets/fields/WhereField/index.js'
+export { QueryPresetsGroupByField } from '../../elements/QueryPresets/fields/GroupByField/index.js'
 
 // elements
 export { ConfirmationModal } from '../../elements/ConfirmationModal/index.js'

test/group-by/collections/Posts/index.ts

@@ -11,6 +11,7 @@ export const PostsCollection: CollectionConfig = {
     groupBy: true,
     defaultColumns: ['title', 'category', 'createdAt', 'updatedAt'],
   },
+  enableQueryPresets: true,
   trash: true,
   fields: [
     {