feat(plugin-import-export): adds sort order control and sync with sort-by field (#13478)

### What?

This PR adds a dedicated `sortOrder` select field (Ascending /
Descending) to the import-export plugin, alongside updates to the
existing `SortBy` component. The new field and component logic keep the
sort field (`sort`) in sync with the selected sort direction.

### Why?

Previously, descending sorting did not work. While the `SortBy` field
could read the list view’s `query.sort` param, if the value contained a
leading dash (e.g. `-title`), it would not be handled correctly. Only
ascending sorts such as `sort=title` worked, and the preview table would
not reflect a descending order.

### How?

- Added a new `sortOrder` select field to the export options schema.
- Implemented a `SortOrder` custom component using ReactSelect:
- On new exports, reads `query.sort` from the list view and sets both
`sortOrder` and `sort` (combined value with or without a leading dash).
  - Handles external changes to `sort` that include a leading dash.
- Updated `SortBy`:
- No longer writes to `sort` during initial hydration—`SortOrder` owns
initial value setting.
- On user field changes, writes the combined value using the current
`sortOrder`.

Author: PatrikKozak

packages/plugin-import-export/src/components/SortBy/index.tsx

@@ -11,8 +11,9 @@ import {
   useField,
   useListQuery,
 } from '@payloadcms/ui'
-import React, { useEffect, useState } from 'react'
+import React, { useEffect, useMemo, useState } from 'react'
 
+import { applySortOrder, stripSortDash } from '../../utilities/sortHelpers.js'
 import { reduceFields } from '../FieldsToExport/reduceFields.js'
 import { useImportExport } from '../ImportExportProvider/index.js'
 import './index.scss'
@@ -21,53 +22,72 @@ const baseClass = 'sort-by-fields'
 
 export const SortBy: SelectFieldClientComponent = (props) => {
   const { id } = useDocumentInfo()
-  const { setValue, value } = useField<string>()
+
+  // The "sort" text field that stores 'title' or '-title'
+  const { setValue: setSort, value: sortRaw } = useField<string>()
+
+  // Sibling order field ('asc' | 'desc') used when writing sort on change
+  const { value: sortOrder = 'asc' } = useField<string>({ path: 'sortOrder' })
+
   const { value: collectionSlug } = useField<string>({ path: 'collectionSlug' })
   const { query } = useListQuery()
   const { getEntityConfig } = useConfig()
   const { collection } = useImportExport()
 
+  // ReactSelect's displayed option
   const [displayedValue, setDisplayedValue] = useState<{
     id: string
     label: ReactNode
     value: string
   } | null>(null)
 
   const collectionConfig = getEntityConfig({ collectionSlug: collectionSlug ?? collection })
-  const fieldOptions = reduceFields({ fields: collectionConfig?.fields })
+  const fieldOptions = useMemo(
+    () => reduceFields({ fields: collectionConfig?.fields }),
+    [collectionConfig?.fields],
+  )
 
-  // Sync displayedValue with value from useField
+  // Normalize the stored value for display (strip the '-') and pick the option
   useEffect(() => {
-    if (!value) {
+    const clean = stripSortDash(sortRaw)
+    if (!clean) {
       setDisplayedValue(null)
       return
     }
 
-    const option = fieldOptions.find((field) => field.value === value)
-    if (option && (!displayedValue || displayedValue.value !== value)) {
+    const option = fieldOptions.find((f) => f.value === clean)
+    if (option && (!displayedValue || displayedValue.value !== clean)) {
       setDisplayedValue(option)
     }
-  }, [displayedValue, fieldOptions, value])
+  }, [sortRaw, fieldOptions, displayedValue])
 
+  // Sync the visible select from list-view query sort,
+  // but no need to write to the "sort" field here — SortOrder owns initial combined value.
   useEffect(() => {
-    if (id || !query?.sort || value) {
+    if (id || !query?.sort || sortRaw) {
+      return
+    }
+
+    if (!query.sort) {
       return
     }
 
-    const option = fieldOptions.find((field) => field.value === query.sort)
+    const clean = stripSortDash(query.sort as string)
+    const option = fieldOptions.find((f) => f.value === clean)
     if (option) {
-      setValue(option.value)
       setDisplayedValue(option)
     }
-  }, [fieldOptions, id, query?.sort, value, setValue])
+  }, [id, query?.sort, sortRaw, fieldOptions])
 
+  // When user selects a different field, store it with the current order applied
   const onChange = (option: { id: string; label: ReactNode; value: string } | null) => {
     if (!option) {
-      setValue('')
+      setSort('')
       setDisplayedValue(null)
     } else {
-      setValue(option.value)
       setDisplayedValue(option)
+      const next = applySortOrder(option.value, String(sortOrder) as 'asc' | 'desc')
+      setSort(next)
     }
   }
 

packages/plugin-import-export/src/components/SortOrder/index.scss

@@ -0,0 +1,3 @@
+.sort-order-field {
+  --field-width: 25%;
+}

packages/plugin-import-export/src/components/SortOrder/index.tsx

@@ -0,0 +1,109 @@
+'use client'
+
+import type { SelectFieldClientComponent } from 'payload'
+
+import { FieldLabel, ReactSelect, useDocumentInfo, useField, useListQuery } from '@payloadcms/ui'
+import React, { useEffect, useMemo, useState } from 'react'
+
+import { applySortOrder, stripSortDash } from '../../utilities/sortHelpers.js'
+import './index.scss'
+
+const baseClass = 'sort-order-field'
+
+type Order = 'asc' | 'desc'
+type OrderOption = { label: string; value: Order }
+
+const options = [
+  { label: 'Ascending', value: 'asc' as const },
+  { label: 'Descending', value: 'desc' as const },
+] as const
+
+const defaultOption: OrderOption = options[0]
+
+// Safely coerce query.sort to a string (ignore arrays)
+const normalizeSortParam = (v: unknown): string | undefined => {
+  if (typeof v === 'string') {
+    return v
+  }
+  if (Array.isArray(v) && typeof v[0] === 'string') {
+    return v[0]
+  }
+  return undefined
+}
+
+export const SortOrder: SelectFieldClientComponent = (props) => {
+  const { id } = useDocumentInfo()
+  const { query } = useListQuery()
+
+  // 'sortOrder' select field: 'asc' | 'desc'
+  const { setValue: setOrder, value: orderValueRaw } = useField<Order>()
+
+  // 'sort' text field: 'title' | '-title'
+  const { setValue: setSort, value: sortRaw } = useField<string>({ path: 'sort' })
+
+  // The current order value, defaulting to 'asc' for UI
+  const orderValue: Order = orderValueRaw || 'asc'
+
+  // Map 'asc' | 'desc' to the option object for ReactSelect
+  const currentOption = useMemo<OrderOption>(
+    () => options.find((o) => o.value === orderValue) ?? defaultOption,
+    [orderValue],
+  )
+  const [displayed, setDisplayed] = useState<null | OrderOption>(currentOption)
+
+  // Derive from list-view query.sort if present
+  useEffect(() => {
+    if (id) {
+      return
+    }
+    const qs = normalizeSortParam(query?.sort)
+    if (!qs) {
+      return
+    }
+
+    const isDesc = qs.startsWith('-')
+    const base = stripSortDash(qs)
+    const order: Order = isDesc ? 'desc' : 'asc'
+
+    setOrder(order)
+    setSort(applySortOrder(base, order))
+  }, [id, query?.sort, setOrder, setSort])
+
+  // Keep the select's displayed option in sync with the stored order
+  useEffect(() => {
+    setDisplayed(currentOption ?? defaultOption)
+  }, [currentOption])
+
+  // Handle manual order changes via ReactSelect:
+  //  - update the order field
+  //  - rewrite the combined "sort" string to add/remove the leading '-'
+  const onChange = (option: null | OrderOption) => {
+    const next = option?.value ?? 'asc'
+    setOrder(next)
+
+    const base = stripSortDash(sortRaw)
+    if (base) {
+      setSort(applySortOrder(base, next))
+    }
+
+    setDisplayed(option ?? defaultOption)
+  }
+
+  return (
+    <div className={baseClass}>
+      <FieldLabel label={props.field.label} path={props.path} />
+      <ReactSelect
+        className={baseClass}
+        disabled={props.readOnly}
+        inputId={`field-${props.path.replace(/\./g, '__')}`}
+        isClearable={false}
+        isSearchable={false}
+        // @ts-expect-error react-select option typing differs from our local type
+        onChange={onChange}
+        options={options as unknown as OrderOption[]}
+        // @ts-expect-error react-select option typing differs from our local type
+        value={displayed}
+      />
+    </div>
+  )
+}

packages/plugin-import-export/src/export/getFields.ts

@@ -118,6 +118,21 @@ export const getFields = (config: Config, pluginConfig?: ImportExportPluginConfi
               // @ts-expect-error - this is not correctly typed in plugins right now
               label: ({ t }) => t('plugin-import-export:field-sort-label'),
             },
+            {
+              name: 'sortOrder',
+              type: 'select',
+              admin: {
+                components: {
+                  Field: '@payloadcms/plugin-import-export/rsc#SortOrder',
+                },
+              },
+              // @ts-expect-error - this is not correctly typed in plugins right now
+              label: ({ t }) => t('plugin-import-export:field-sort-order-label'),
+              options: [
+                { label: 'Ascending', value: 'asc' },
+                { label: 'Descending', value: 'desc' },
+              ],
+            },
             ...(localeField ? [localeField] : []),
             {
               name: 'drafts',

packages/plugin-import-export/src/exports/rsc.ts

@@ -7,3 +7,4 @@ export { Page } from '../components/Page/index.js'
 export { Preview } from '../components/Preview/index.js'
 export { SelectionToUseField } from '../components/SelectionToUseField/index.js'
 export { SortBy } from '../components/SortBy/index.js'
+export { SortOrder } from '../components/SortOrder/index.js'

packages/plugin-import-export/src/translations/languages/ar.ts

@@ -15,6 +15,7 @@ export const arTranslations: PluginDefaultTranslationsObject = {
     'field-page-label': 'صفحة',
     'field-selectionToUse-label': 'اختيار للاستخدام',
     'field-sort-label': 'ترتيب حسب',
+    'field-sort-order-label': 'ترتيب',
     'selectionToUse-allDocuments': 'استخدم جميع الوثائق',
     'selectionToUse-currentFilters': 'استخدم الفلاتر الحالية',
     'selectionToUse-currentSelection': 'استخدم الاختيار الحالي',

packages/plugin-import-export/src/translations/languages/az.ts

@@ -15,6 +15,7 @@ export const azTranslations: PluginDefaultTranslationsObject = {
     'field-page-label': 'Səhifə',
     'field-selectionToUse-label': 'İstifadə etmək üçün seçim',
     'field-sort-label': 'Sırala',
+    'field-sort-order-label': 'Sıralama',
     'selectionToUse-allDocuments': 'Bütün sənədlərdən istifadə edin',
     'selectionToUse-currentFilters': 'Cari filtrlərdən istifadə edin',
     'selectionToUse-currentSelection': 'Cari seçimi istifadə edin',

packages/plugin-import-export/src/translations/languages/bg.ts

@@ -15,6 +15,7 @@ export const bgTranslations: PluginDefaultTranslationsObject = {
     'field-page-label': 'Страница',
     'field-selectionToUse-label': 'Избор за използване',
     'field-sort-label': 'Сортирай по',
+    'field-sort-order-label': 'Ред на сортиране',
     'selectionToUse-allDocuments': 'Използвайте всички документи',
     'selectionToUse-currentFilters': 'Използвайте текущите филтри',
     'selectionToUse-currentSelection': 'Използвайте текущия избор',

packages/plugin-import-export/src/translations/languages/ca.ts

@@ -15,6 +15,7 @@ export const caTranslations: PluginDefaultTranslationsObject = {
     'field-page-label': 'Pàgina',
     'field-selectionToUse-label': 'Selecció per utilitzar',
     'field-sort-label': 'Ordena per',
+    'field-sort-order-label': 'Ordre de classificació',
     'selectionToUse-allDocuments': 'Utilitzeu tots els documents',
     'selectionToUse-currentFilters': 'Utilitza els filtres actuals',
     'selectionToUse-currentSelection': 'Utilitza la selecció actual',

packages/plugin-import-export/src/translations/languages/cs.ts

@@ -15,6 +15,7 @@ export const csTranslations: PluginDefaultTranslationsObject = {
     'field-page-label': 'Stránka',
     'field-selectionToUse-label': 'Výběr k použití',
     'field-sort-label': 'Seřadit podle',
+    'field-sort-order-label': 'Řazení',
     'selectionToUse-allDocuments': 'Použijte všechny dokumenty',
     'selectionToUse-currentFilters': 'Použijte aktuální filtry',
     'selectionToUse-currentSelection': 'Použijte aktuální výběr',