feat: adds admin.formatDocURL function to control list view linking (#13773)

### What?

Adds a new `formatDocURL` function to collection admin configuration
that allows users to control the linkable state and URLs of first column
fields in list views.

### Why?

To provide a way to disable automatic link creation from the first
column or provide custom URLs based on document data, user permissions,
view context, and document state.

### How?

- Added `formatDocURL` function type to `CollectionAdminOptions` that
receives document data, default URL, request context, collection slug,
and view type
- Modified `renderCell` to call the function when available and handle
three return types:
  - `null`: disables linking entirely
  - `string`: uses custom URL
  - other: falls back to no linking for safety
- Added function to server-only properties to prevent React Server
Components serialization issues
- Updated `DefaultCell` component to support custom `linkURL` prop


---
- To see the specific tasks where the Asana app for GitHub is being
used, see below:
  - https://app.asana.com/0/0/1211211792037945

Author: PatrikKozak

docs/configuration/collections.mdx

@@ -136,6 +136,7 @@ The following options are available:
 | `enableRichTextLink`         | The [Rich Text](../fields/rich-text) field features a `Link` element which allows for users to automatically reference related documents within their rich text. Set to `true` by default.                                   |
 | `enableRichTextRelationship` | The [Rich Text](../fields/rich-text) field features a `Relationship` element which allows for users to automatically reference related documents within their rich text. Set to `true` by default.                           |
 | `folders`                    | A boolean to enable folders for a given collection. Defaults to `false`. [More details](../folders/overview).                                                                                                                |
+| `formatDocURL`               | Function to customize document links in the List View. Return `null` to disable linking, or a string for custom URLs. [More details](#format-document-urls).                                                                 |
 | `meta`                       | Page metadata overrides to apply to this Collection within the Admin Panel. [More details](../admin/metadata).                                                                                                               |
 | `preview`                    | Function to generate preview URLs within the Admin Panel that can point to your app. [More details](../admin/preview).                                                                                                       |
 | `livePreview`                | Enable real-time editing for instant visual feedback of your front-end application. [More details](../live-preview/overview).                                                                                                |
@@ -333,6 +334,76 @@ export const Posts: CollectionConfig = {
 }
 ```
 
+### Format Document URLs
+
+The `formatDocURL` function allows you to customize how document links are generated in the List View. This is useful for disabling links for certain documents, redirecting to custom destinations, or modifying URLs based on user context or document state.
+
+To define a custom document URL formatter, use the `admin.formatDocURL` property in your Collection Config:
+
+```ts
+import type { CollectionConfig } from 'payload'
+
+export const Posts: CollectionConfig = {
+  // ...
+  admin: {
+    formatDocURL: ({ doc, defaultURL, req, collectionSlug, viewType }) => {
+      // Disable linking for documents with specific status
+      if (doc.status === 'private') {
+        return null
+      }
+
+      // Custom destination for featured posts
+      if (doc.featured) {
+        return '/admin/featured-posts'
+      }
+
+      // Add query parameters based on user role
+      if (req.user?.role === 'admin') {
+        return defaultURL + '?admin=true'
+      }
+
+      // Use default URL for all other cases
+      return defaultURL
+    },
+  },
+}
+```
+
+The `formatDocURL` function receives the following arguments:
+
+| Argument         | Description                                                                                                                            |
+| ---------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
+| `doc`            | The document data for the current row                                                                                                  |
+| `defaultURL`     | The default URL that Payload would normally generate for this document. You can return this as-is, modify it, or replace it entirely.  |
+| `req`            | The full [PayloadRequest](../types/payload-request) object, providing access to user context, payload instance, and other request data |
+| `collectionSlug` | The slug of the current collection                                                                                                     |
+| `viewType`       | The current view context (`'list'`, `'trash'`, etc.) where the link is being generated                                                 |
+
+The function should return:
+
+- `null` to disable the link entirely (no link will be rendered)
+- A `string` containing the custom URL to use for the link
+- The `defaultURL` parameter to use Payload's default linking behavior
+
+<Banner type="success">
+  **Tip:** The `defaultURL` parameter saves you from having to reconstruct URLs
+  manually. You can modify it by appending query parameters or use it as a
+  fallback for your custom logic.
+</Banner>
+
+#### Examples
+
+**Disable linking for certain users:**
+
+```ts
+formatDocURL: ({ defaultURL, req }) => {
+  if (req.user?.role === 'editor') {
+    return null // No link rendered
+  }
+  return defaultURL
+}
+```
+
 ## GraphQL
 
 You can completely disable GraphQL for this collection by passing `graphQL: false` to your collection config. This will completely disable all queries, mutations, and types from appearing in your GraphQL schema.

packages/next/src/views/List/index.tsx

@@ -280,6 +280,7 @@ export const renderListView = async (
           orderableFieldName: collectionConfig.orderable === true ? '_order' : undefined,
           payload: req.payload,
           query,
+          req,
           useAsTitle: collectionConfig.admin.useAsTitle,
           viewType,
         }))

packages/payload/src/admin/elements/Cell.ts

@@ -77,6 +77,7 @@ export type DefaultCellComponentProps<
   customCellProps?: Record<string, any>
   field: TField
   link?: boolean
+  linkURL?: string
   onClick?: (args: {
     cellData: unknown
     collectionSlug: SanitizedCollectionConfig['slug']

packages/payload/src/collections/config/client.ts

@@ -29,7 +29,7 @@ export type ServerOnlyCollectionProperties = keyof Pick<
 
 export type ServerOnlyCollectionAdminProperties = keyof Pick<
   SanitizedCollectionConfig['admin'],
-  'baseFilter' | 'baseListFilter' | 'components' | 'hidden'
+  'baseFilter' | 'baseListFilter' | 'components' | 'formatDocURL' | 'hidden'
 >
 
 export type ServerOnlyUploadProperties = keyof Pick<
@@ -50,6 +50,7 @@ export type ClientCollectionConfig = {
     SanitizedCollectionConfig['admin'],
     | 'components'
     | 'description'
+    | 'formatDocURL'
     | 'joins'
     | 'livePreview'
     | 'preview'
@@ -97,6 +98,7 @@ const serverOnlyCollectionAdminProperties: Partial<ServerOnlyCollectionAdminProp
   'baseFilter',
   'baseListFilter',
   'components',
+  'formatDocURL',
   // 'preview' is handled separately
   // `livePreview` is handled separately
 ]

packages/payload/src/collections/config/types.ts

@@ -2,7 +2,7 @@
 import type { GraphQLInputObjectType, GraphQLNonNull, GraphQLObjectType } from 'graphql'
 import type { DeepRequired, IsAny, MarkOptional } from 'ts-essentials'
 
-import type { CustomUpload } from '../../admin/types.js'
+import type { CustomUpload, ViewTypes } from '../../admin/types.js'
 import type { Arguments as MeArguments } from '../../auth/operations/me.js'
 import type {
   Arguments as RefreshArguments,
@@ -396,6 +396,27 @@ export type CollectionAdminOptions = {
   enableListViewSelectAPI?: boolean
   enableRichTextLink?: boolean
   enableRichTextRelationship?: boolean
+  /**
+   * Function to format the URL for document links in the list view.
+   * Return null to disable linking for that document.
+   * Return a string to customize the link destination.
+   * If not provided, uses the default admin edit URL.
+   */
+  formatDocURL?: (args: {
+    collectionSlug: string
+    /**
+     * The default URL that would normally be used for this document link.
+     * You can return this as-is, modify it, or completely replace it.
+     */
+    defaultURL: string
+    doc: Record<string, unknown>
+    req: PayloadRequest
+    /**
+     * The current view context where the link is being generated.
+     * Most relevant values for document linking are 'list' and 'trash'.
+     */
+    viewType?: ViewTypes
+  }) => null | string
   /**
    * Specify a navigational group for collections in the admin sidebar.
    * - Provide a string to place the entity in a custom group.

packages/ui/src/elements/Table/DefaultCell/index.tsx

@@ -22,6 +22,7 @@ export const DefaultCell: React.FC<DefaultCellComponentProps> = (props) => {
     field,
     field: { admin },
     link,
+    linkURL,
     onClick: onClickFromProps,
     rowData,
     viewType,
@@ -62,12 +63,18 @@ export const DefaultCell: React.FC<DefaultCellComponentProps> = (props) => {
   if (link) {
     wrapElementProps.prefetch = false
     WrapElement = Link
-    wrapElementProps.href = collectionConfig?.slug
-      ? formatAdminURL({
-          adminRoute,
-          path: `/collections/${collectionConfig?.slug}${viewType === 'trash' ? '/trash' : ''}/${encodeURIComponent(rowData.id)}`,
-        })
-      : ''
+
+    // Use custom linkURL if provided, otherwise use default URL generation
+    if (linkURL) {
+      wrapElementProps.href = linkURL
+    } else {
+      wrapElementProps.href = collectionConfig?.slug
+        ? formatAdminURL({
+            adminRoute,
+            path: `/collections/${collectionConfig?.slug}${viewType === 'trash' ? '/trash' : ''}/${encodeURIComponent(rowData.id)}`,
+          })
+        : ''
+    }
   }
 
   if (typeof onClick === 'function') {

packages/ui/src/providers/TableColumns/buildColumnState/index.tsx

@@ -10,6 +10,7 @@ import type {
   Field,
   PaginatedDocs,
   Payload,
+  PayloadRequest,
   SanitizedCollectionConfig,
   ServerComponentProps,
   StaticLabel,
@@ -46,6 +47,7 @@ export type BuildColumnStateArgs = {
   enableRowTypes?: boolean
   i18n: I18nClient
   payload: Payload
+  req?: PayloadRequest
   serverFields: Field[]
   sortColumnProps?: Partial<SortColumnProps>
   useAsTitle: SanitizedCollectionConfig['admin']['useAsTitle']
@@ -79,6 +81,7 @@ export const buildColumnState = (args: BuildColumnStateArgs): Column[] => {
     enableRowSelections,
     i18n,
     payload,
+    req,
     serverFields,
     sortColumnProps,
     useAsTitle,
@@ -249,6 +252,7 @@ export const buildColumnState = (args: BuildColumnStateArgs): Column[] => {
               i18n,
               isLinkedColumn: enableLinkedCell && colIndex === activeColumnsIndices[0],
               payload,
+              req,
               rowIndex,
               serverField,
               viewType,

packages/ui/src/providers/TableColumns/buildColumnState/renderCell.tsx

@@ -6,10 +6,12 @@ import type {
   Document,
   Field,
   Payload,
+  PayloadRequest,
   ViewTypes,
 } from 'payload'
 
 import { MissingEditorProp } from 'payload'
+import { formatAdminURL } from 'payload/shared'
 
 import { RenderCustomComponent } from '../../../elements/RenderCustomComponent/index.js'
 import { RenderServerComponent } from '../../../elements/RenderServerComponent/index.js'
@@ -31,6 +33,7 @@ type RenderCellArgs = {
   readonly i18n: I18nClient
   readonly isLinkedColumn: boolean
   readonly payload: Payload
+  readonly req?: PayloadRequest
   readonly rowIndex: number
   readonly serverField: Field
   readonly viewType?: ViewTypes
@@ -45,6 +48,7 @@ export function renderCell({
   i18n,
   isLinkedColumn,
   payload,
+  req,
   rowIndex,
   serverField,
   viewType,
@@ -62,10 +66,49 @@ export function renderCell({
     ('accessor' in clientField ? (clientField.accessor as string) : undefined) ??
     ('name' in clientField ? clientField.name : undefined)
 
+  // Check if there's a custom formatDocURL function for this linked column
+  let shouldLink = isLinkedColumn
+  let customLinkURL: string | undefined
+
+  if (isLinkedColumn && req) {
+    const collectionConfig = payload.collections[collectionSlug]?.config
+    const formatDocURL = collectionConfig?.admin?.formatDocURL
+
+    if (typeof formatDocURL === 'function') {
+      // Generate the default URL that would normally be used
+      const adminRoute = req.payload.config.routes?.admin || '/admin'
+      const defaultURL = formatAdminURL({
+        adminRoute,
+        path: `/collections/${collectionSlug}${viewType === 'trash' ? '/trash' : ''}/${encodeURIComponent(String(doc.id))}`,
+      })
+
+      const customURL = formatDocURL({
+        collectionSlug,
+        defaultURL,
+        doc,
+        req,
+        viewType,
+      })
+
+      if (customURL === null) {
+        // formatDocURL returned null = disable linking entirely
+        shouldLink = false
+      } else if (typeof customURL === 'string') {
+        // formatDocURL returned a string = use custom URL
+        shouldLink = true
+        customLinkURL = customURL
+      } else {
+        // formatDocURL returned unexpected type = disable linking for safety
+        shouldLink = false
+      }
+    }
+  }
+
   const cellClientProps: DefaultCellComponentProps = {
     ...baseCellClientProps,
     cellData: 'name' in clientField ? findValueFromPath(doc, accessor) : undefined,
-    link: isLinkedColumn,
+    link: shouldLink,
+    linkURL: customLinkURL,
     rowData: doc,
   }
 
@@ -78,7 +121,8 @@ export function renderCell({
     customCellProps: baseCellClientProps.customCellProps,
     field: serverField,
     i18n,
-    link: cellClientProps.link,
+    link: shouldLink,
+    linkURL: customLinkURL,
     onClick: baseCellClientProps.onClick,
     payload,
     rowData: doc,

packages/ui/src/utilities/renderTable.tsx

@@ -10,6 +10,7 @@ import type {
   ListQuery,
   PaginatedDocs,
   Payload,
+  PayloadRequest,
   SanitizedCollectionConfig,
   ViewTypes,
 } from 'payload'
@@ -80,6 +81,7 @@ export const renderTable = ({
   payload,
   query,
   renderRowTypes,
+  req,
   tableAppearance,
   useAsTitle,
   viewType,
@@ -102,6 +104,7 @@ export const renderTable = ({
   payload: Payload
   query?: ListQuery
   renderRowTypes?: boolean
+  req?: PayloadRequest
   tableAppearance?: 'condensed' | 'default'
   useAsTitle: CollectionConfig['admin']['useAsTitle']
   viewType?: ViewTypes
@@ -159,6 +162,7 @@ export const renderTable = ({
     | 'enableRowSelections'
     | 'i18n'
     | 'payload'
+    | 'req'
     | 'serverFields'
     | 'useAsTitle'
     | 'viewType'
@@ -170,6 +174,7 @@ export const renderTable = ({
     // sortColumnProps,
     customCellProps,
     payload,
+    req,
     serverFields,
     useAsTitle,
     viewType,