feat: move trash out of beta and delete access can now be limited to trash only (#15210)

### Access control can be limited to only trash

You can now limit users to only trash without being able to permanently
delete:

```ts
import type { CollectionConfig } from 'payload'

export const Posts: CollectionConfig = {
  slug: 'posts',
  trash: true,
  access: {
    delete: ({ req: { user }, data }) => {
      // Not logged in - no access
      if (!user) {
        return false
      }

      // Admins can do anything (trash or permanently delete)
      if (user.roles?.includes('admin')) {
        return true
      }

      // Regular users: check what operation they're attempting
      // If data.deletedAt is being set, it's a trash operation - allow it
      if (data?.deletedAt) {
        return true
      }

      // Otherwise it's a permanent delete - deny for non-admins
      return false
    },
  },
  fields: [
    // ...
  ],
}
```

---------

Co-authored-by: Patrik Kozak <35232443+PatrikKozak@users.noreply.github.com>
Co-authored-by: Claude Sonnet 4.5 <noreply@anthropic.com>

Author: 3 people

docs/access-control/collections.mdx

@@ -258,10 +258,18 @@ export const canDeleteCustomer: Access<Customer> = async ({ req, id }) => {
 
 The following arguments are provided to the `delete` function:
 
-| Option    | Description                                                                                                                                            |
-| --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| **`req`** | The [Request](https://developer.mozilla.org/en-US/docs/Web/API/Request) object with additional `user` property, which is the currently logged in user. |
-| **`id`**  | `id` of document requested to delete.                                                                                                                  |
+| Option     | Description                                                                                                                                                                          |
+| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| **`req`**  | The [Request](https://developer.mozilla.org/en-US/docs/Web/API/Request) object with additional `user` property, which is the currently logged in user.                               |
+| **`id`**   | `id` of document requested to delete.                                                                                                                                                |
+| **`data`** | The data being set on the document. For [Trash-enabled](../trash/overview) collections, check `data.deletedAt` to differentiate between soft delete and permanent delete operations. |
+
+<Banner type="success">
+  **Tip:** For Collections with [Trash](../trash/overview) enabled, you can use
+  the `data` argument to allow users to soft delete (trash) documents while
+  restricting permanent deletion. See [Trash Access
+  Control](../trash/overview#access-control) for examples.
+</Banner>
 
 ### Admin
 

docs/trash/overview.mdx

@@ -10,11 +10,6 @@ Trash (also known as soft delete) allows documents to be marked as deleted witho
 
 Soft delete is a safer way to manage content lifecycle, giving editors a chance to review and recover documents that may have been deleted by mistake.
 
-<Banner type="warning">
-  **Note:** The Trash feature is currently in beta and may be subject to change
-  in minor version updates.
-</Banner>
-
 ## Collection Configuration
 
 To enable soft deleting for a collection, set the `trash` property to `true`:
@@ -183,12 +178,85 @@ query {
 
 ## Access Control
 
-All trash-related actions (delete, permanent delete) respect the `delete` access control defined in your collection config.
+All trash-related actions (soft delete, permanent delete, restore) respect the `delete` access control defined in your collection config.
 
 This means:
 
 - If a user is denied delete access, they cannot soft delete or permanently delete documents
 
+### Differentiating Between Trash and Permanent Delete
+
+You can configure access control to allow some users to trash documents while restricting permanent deletion to admins only. This is useful when you want editors to be able to "delete" content (move to trash) but only allow administrators to permanently remove data.
+
+The `delete` access control function receives a `data` argument that contains the document data being set during the operation:
+
+- **When trashing:** `data.deletedAt` will be set to a timestamp
+- **When permanently deleting:** `data` will be `undefined`
+
+This pattern is similar to how `publish` access control works with `data._status`.
+
+#### Example: Allow All Users to Trash, Only Admins to Permanently Delete
+
+```ts
+import type { CollectionConfig } from 'payload'
+
+export const Posts: CollectionConfig = {
+  slug: 'posts',
+  trash: true,
+  access: {
+    delete: ({ req: { user }, data }) => {
+      // Not logged in - no access
+      if (!user) {
+        return false
+      }
+
+      // Admins can do anything (trash or permanently delete)
+      if (user.roles?.includes('admin')) {
+        return true
+      }
+
+      // Regular users: check what operation they're attempting
+      // If data.deletedAt is being set, it's a trash operation - allow it
+      if (data?.deletedAt) {
+        return true
+      }
+
+      // Otherwise it's a permanent delete - deny for non-admins
+      return false
+    },
+  },
+  fields: [
+    // ...
+  ],
+}
+```
+
+#### Example: Only Admins Can Delete (Both Trash and Permanent)
+
+```ts
+import type { CollectionConfig } from 'payload'
+
+export const SensitiveData: CollectionConfig = {
+  slug: 'sensitive-data',
+  trash: true,
+  access: {
+    delete: ({ req: { user } }) => {
+      // Only allow admins to trash or permanently delete
+      return Boolean(user?.roles?.includes('admin'))
+    },
+  },
+  fields: [
+    // ...
+  ],
+}
+```
+
+In the Admin Panel, when a user has permission to trash but not permanently delete:
+
+- The delete button will be visible
+- The "Delete permanently" checkbox in the confirmation modal will be hidden
+- The user can only move documents to trash
+
 ## Versions and Trash
 
 When a document is soft-deleted:

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

@@ -63,13 +63,18 @@ export async function AccountView({ initPageResult, params, searchParams }: Admi
     })
 
     // Get permissions
-    const { docPermissions, hasPublishPermission, hasSavePermission } =
-      await getDocumentPermissions({
-        id: user.id,
-        collectionConfig,
-        data,
-        req,
-      })
+    const {
+      docPermissions,
+      hasDeletePermission,
+      hasPublishPermission,
+      hasSavePermission,
+      hasTrashPermission,
+    } = await getDocumentPermissions({
+      id: user.id,
+      collectionConfig,
+      data,
+      req,
+    })
 
     // Build initial form state from data
     const { state: formState } = await buildFormState({
@@ -124,9 +129,11 @@ export async function AccountView({ initPageResult, params, searchParams }: Admi
         collectionSlug={userSlug}
         currentEditor={currentEditor}
         docPermissions={docPermissions}
+        hasDeletePermission={hasDeletePermission}
         hasPublishedDoc={hasPublishedDoc}
         hasPublishPermission={hasPublishPermission}
         hasSavePermission={hasSavePermission}
+        hasTrashPermission={hasTrashPermission}
         id={user?.id}
         initialData={data}
         initialState={formState}

packages/next/src/views/Document/getDocumentPermissions.tsx

@@ -24,13 +24,17 @@ export const getDocumentPermissions = async (args: {
   req: PayloadRequest
 }): Promise<{
   docPermissions: SanitizedDocumentPermissions
+  hasDeletePermission: boolean
   hasPublishPermission: boolean
   hasSavePermission: boolean
+  hasTrashPermission: boolean
 }> => {
   const { id, collectionConfig, data = {}, globalConfig, req } = args
 
   let docPermissions: SanitizedDocumentPermissions
   let hasPublishPermission = false
+  let hasTrashPermission = false
+  let hasDeletePermission = false
 
   if (collectionConfig) {
     try {
@@ -61,6 +65,39 @@ export const getDocumentPermissions = async (args: {
           })
         ).update
       }
+
+      if (collectionConfig.trash) {
+        const { deletedAt: _, ...dataWithoutDeletedAt } = data || {}
+
+        const [trashPermissionResult, deletePermissionResult] = await Promise.all([
+          docAccessOperation({
+            id,
+            collection: {
+              config: collectionConfig,
+            },
+            data: {
+              ...data,
+              deletedAt: new Date().toISOString(),
+            },
+            req,
+          }),
+          docAccessOperation({
+            id,
+            collection: {
+              config: collectionConfig,
+            },
+            data: dataWithoutDeletedAt,
+            req,
+          }),
+        ])
+
+        hasTrashPermission = trashPermissionResult.delete
+        hasDeletePermission = deletePermissionResult.delete
+      } else {
+        // When trash is not enabled, delete permission is straightforward
+        hasDeletePermission = 'delete' in docPermissions ? Boolean(docPermissions.delete) : false
+        hasTrashPermission = false
+      }
     } catch (err) {
       logError({ err, payload: req.payload })
     }
@@ -86,6 +123,10 @@ export const getDocumentPermissions = async (args: {
           })
         ).update
       }
+
+      // Globals don't support trash
+      hasDeletePermission = false
+      hasTrashPermission = false
     } catch (err) {
       logError({ err, payload: req.payload })
     }
@@ -104,7 +145,9 @@ export const getDocumentPermissions = async (args: {
 
   return {
     docPermissions,
+    hasDeletePermission,
     hasPublishPermission,
     hasSavePermission,
+    hasTrashPermission,
   }
 }

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

@@ -162,7 +162,13 @@ export const renderDocument = async ({
 
   const [
     docPreferences,
-    { docPermissions, hasPublishPermission, hasSavePermission },
+    {
+      docPermissions,
+      hasDeletePermission,
+      hasPublishPermission,
+      hasSavePermission,
+      hasTrashPermission,
+    },
     { currentEditor, isLocked, lastUpdateTime },
     entityPreferences,
   ] = await Promise.all([
@@ -399,9 +405,11 @@ export const renderDocument = async ({
         disableActions={disableActions ?? false}
         docPermissions={docPermissions}
         globalSlug={globalConfig?.slug}
+        hasDeletePermission={hasDeletePermission}
         hasPublishedDoc={hasPublishedDoc}
         hasPublishPermission={hasPublishPermission}
         hasSavePermission={hasSavePermission}
+        hasTrashPermission={hasTrashPermission}
         id={id}
         initialData={doc}
         initialState={formState}

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

@@ -354,7 +354,13 @@ export const renderListView = async (
   })
 
   const hasCreatePermission = permissions?.collections?.[collectionSlug]?.create
-  const hasDeletePermission = permissions?.collections?.[collectionSlug]?.delete
+
+  const { hasDeletePermission, hasTrashPermission } = await getDocumentPermissions({
+    collectionConfig,
+    // Empty object serves as base for computing differentiated trash/delete permissions
+    data: {},
+    req,
+  })
 
   // Check if there's a notFound query parameter (document ID that wasn't found)
   const notFoundDocId = typeof searchParams?.notFound === 'string' ? searchParams.notFound : null
@@ -379,6 +385,7 @@ export const renderListView = async (
       collectionSlug,
       hasCreatePermission,
       hasDeletePermission,
+      hasTrashPermission,
       newDocumentURL,
     },
     collectionConfig,
@@ -416,6 +423,7 @@ export const renderListView = async (
               enableRowSelections,
               hasCreatePermission,
               hasDeletePermission,
+              hasTrashPermission,
               listPreferences: collectionPreferences,
               newDocumentURL,
               queryPreset,

packages/payload/src/admin/views/list.ts

@@ -46,6 +46,7 @@ export type ListViewClientProps = {
   enableRowSelections?: boolean
   hasCreatePermission: boolean
   hasDeletePermission?: boolean
+  hasTrashPermission?: boolean
   /**
    * @deprecated
    */
@@ -66,6 +67,7 @@ export type ListViewSlotSharedClientProps = {
   collectionSlug: SanitizedCollectionConfig['slug']
   hasCreatePermission: boolean
   hasDeletePermission?: boolean
+  hasTrashPermission?: boolean
   newDocumentURL: string
 }
 

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

@@ -722,7 +722,6 @@ export type CollectionConfig<TSlug extends CollectionSlug = any> = {
    * This allows documents to be marked as deleted without being permanently removed.
    * The `deletedAt` field will be set to the current date and time when a document is trashed.
    *
-   * @experimental This is a beta feature and its behavior may be refined in future releases.
    * @default false
    */
   trash?: boolean

packages/payload/src/collections/operations/update.ts

@@ -155,7 +155,11 @@ export const updateOperation = async <
 
     // Enforce delete access if performing a soft-delete (trash)
     if (isTrashAttempt && !overrideAccess) {
-      const deleteAccessResult = await executeAccess({ req }, collectionConfig.access.delete)
+      // Pass data so access function can check data.deletedAt to know it's a trash attempt
+      const deleteAccessResult = await executeAccess(
+        { data: bulkUpdateData, req },
+        collectionConfig.access.delete,
+      )
       fullWhere = combineQueries(fullWhere, deleteAccessResult)
     }
 

packages/payload/src/collections/operations/updateByID.ts

@@ -137,7 +137,8 @@ export const updateByIDOperation = async <
       data.deletedAt != null
 
     if (isTrashAttempt && !overrideAccess) {
-      const deleteAccessResult = await executeAccess({ req }, collectionConfig.access.delete)
+      // Pass data so access function can check data.deletedAt to know it's a trash attempt
+      const deleteAccessResult = await executeAccess({ data, req }, collectionConfig.access.delete)
       fullWhere = combineQueries(fullWhere, deleteAccessResult)
     }