feat: add support for custom Status component in document controls (#11154)

Spreizu · Elmo Egers · Elmo Egers · web-flow · commit ef863e6b641f · 2026-01-13T19:11:32.000Z
### What?

This PR adds the ability to replace the Status section of the document
or global edit view, without the need to replace the whole Edit view.

### Why?

In certain cases there may be a need to add custom elements before or
after the original Status component. In our case, we need to replace the
whole Status component to support custom locale publishing logic and
also for additional status indicators for the users.

### How?

**In the `docs` package:**
- Added a description of the Status component to the components section
within both the collections and globals sections.

**In the `next` package:**
- Enabled rendering of the custom Status component.
- Modified the Live Preview components to include the Status component
prop.

**In the `payload` package:**
- Introduced type definitions for the Status component.
- Implemented importMap generation for the Status component.

**In the `ui` package:**
- Modified the Edit view to pass the Status component to
DocumentControls.
- Updated the DocumentControls component to accept and render a custom
Status component if defined.


Now supports the following Status component in admin

```ts
admin: {
  components: {
    edit: {
      Status: '/components/Status/index.tsx#Status',
    },
  },
},
```

---------

Co-authored-by: Elmo Egers &lt;elmo.egers@smit.ee&gt;
Co-authored-by: Elmo Egers &lt;uplaymedia@gmail.com&gt;
Co-authored-by: Jacob Fletcher &lt;jacobsfletch@gmail.com&gt;
diff --git a/docs/configuration/collections.mdx b/docs/configuration/collections.mdx
@@ -212,6 +212,7 @@ The following options are available:
 | `editMenuItems`          | Inject custom components within the 3-dot menu dropdown located in the document controls bar. [More details](../custom-components/edit-view#editmenuitems).                                             |
 | `SaveButton`             | Replace the default Save Button within the Edit View. [Drafts](../versions/drafts) must be disabled. [More details](../custom-components/edit-view#savebutton).                                         |
 | `SaveDraftButton`        | Replace the default Save Draft Button within the Edit View. [Drafts](../versions/drafts) must be enabled and autosave must be disabled. [More details](../custom-components/edit-view#savedraftbutton). |
+| `Status`                 | Replace the default Status component within the Edit View. [Drafts](../versions/drafts) must be enabled. [More details](../custom-components/edit-view#status).                                         |
 | `PublishButton`          | Replace the default Publish Button within the Edit View. [Drafts](../versions/drafts) must be enabled. [More details](../custom-components/edit-view#publishbutton).                                    |
 | `PreviewButton`          | Replace the default Preview Button within the Edit View. [Preview](../admin/preview) must be enabled. [More details](../custom-components/edit-view#previewbutton).                                     |
 | `Upload`                 | Replace the default Upload component within the Edit View. [Upload](../upload/overview) must be enabled. [More details](../custom-components/edit-view#upload).                                         |
diff --git a/docs/configuration/globals.mdx b/docs/configuration/globals.mdx
@@ -187,6 +187,7 @@ The following options are available:
 | `SaveDraftButton`        | Replace the default Save Draft Button with a Custom Component. [Drafts](../versions/drafts) must be enabled and autosave must be disabled. [More details](../custom-components/edit-view#savedraftbutton). |
 | `PublishButton`          | Replace the default Publish Button with a Custom Component. [Drafts](../versions/drafts) must be enabled. [More details](../custom-components/edit-view#publishbutton).                                    |
 | `PreviewButton`          | Replace the default Preview Button with a Custom Component. [Preview](../admin/preview) must be enabled. [More details](../custom-components/edit-view#previewbutton).                                     |
+| `Status`                 | Replace the default Status component with a Custom Component. [Drafts](../versions/drafts) must be enabled. [More details](../custom-components/edit-view#status).                                         |
 
 <Banner type="success">
   **Note:** For details on how to build Custom Components, see [Building Custom
diff --git a/docs/custom-components/edit-view.mdx b/docs/custom-components/edit-view.mdx
@@ -110,6 +110,7 @@ The following options are available:
 | `PublishButton`          | A button that publishes the current document. [More details](#publishbutton).                                                |
 | `PreviewButton`          | A button that previews the current document. [More details](#previewbutton).                                                 |
 | `Description`            | A description of the Collection. [More details](#description).                                                               |
+| `Status`                 | A component that represents the status of the current document. [More details](#status).                                     |
 | `Upload`                 | A file upload component. [More details](#upload).                                                                            |
 
 #### Globals
@@ -144,6 +145,7 @@ The following options are available:
 | `PublishButton`          | A button that publishes the current document. [More details](#publishbutton).                                                |
 | `PreviewButton`          | A button that previews the current document. [More details](#previewbutton).                                                 |
 | `Description`            | A description of the Global. [More details](#description).                                                                   |
+| `Status`                 | A component that represents the status of the global. [More details](#status).                                               |
 
 ### SaveButton
 
@@ -548,6 +550,29 @@ export function MyDescriptionComponent(props: ViewDescriptionClientProps) {
 }
 ```
 
+### Status
+
+The `Status` property allows you to render a component that represents the collection or global status in the Edit View.
+
+To add an `Status` component, use the `components.edit.Status` property in your [Collection Config](../configuration/collections):
+
+```ts
+import type { CollectionConfig } from 'payload'
+
+export const MyCollection: CollectionConfig = {
+  // ...
+  admin: {
+    components: {
+      edit: {
+        // highlight-start
+        Status: '/path/to/MyStatusComponent',
+        // highlight-end
+      },
+    },
+  },
+}
+```
+
 ### Upload
 
 The `Upload` property allows you to render a custom file upload component in the Edit View. This is only available for upload-enabled Collections.
diff --git a/packages/next/src/views/Document/renderDocumentSlots.tsx b/packages/next/src/views/Document/renderDocumentSlots.tsx
@@ -120,6 +120,20 @@ export const renderDocumentSlots: (args: {
     })
   }
 
+  if (collectionConfig?.versions?.drafts || globalConfig?.versions?.drafts) {
+    const CustomStatus =
+      collectionConfig?.admin?.components?.edit?.Status ||
+      globalConfig?.admin?.components?.elements?.Status
+
+    if (CustomStatus) {
+      components.Status = RenderServerComponent({
+        Component: CustomStatus,
+        importMap: req.payload.importMap,
+        serverProps,
+      })
+    }
+  }
+
   if (hasSavePermission) {
     if (hasDraftsEnabled(collectionConfig || globalConfig)) {
       const CustomPublishButton =
diff --git a/packages/payload/src/admin/elements/Status.ts b/packages/payload/src/admin/elements/Status.ts
@@ -0,0 +1,3 @@
+import type { CustomComponent } from '../../config/types.js'
+
+export type CustomStatus = CustomComponent
diff --git a/packages/payload/src/admin/types.ts b/packages/payload/src/admin/types.ts
@@ -81,6 +81,8 @@ export type {
   SaveDraftButtonServerPropsOnly,
 } from './elements/SaveDraftButton.js'
 
+export type { CustomStatus } from './elements/Status.js'
+
 export type { Column } from './elements/Table.js'
 
 export type { CustomUpload } from './elements/Upload.js'
@@ -567,6 +569,7 @@ export type DocumentSlots = {
   PublishButton?: React.ReactNode
   SaveButton?: React.ReactNode
   SaveDraftButton?: React.ReactNode
+  Status?: React.ReactNode
   Upload?: React.ReactNode
   UploadControls?: React.ReactNode
 }
diff --git a/packages/payload/src/bin/generateImportMap/iterateCollections.ts b/packages/payload/src/bin/generateImportMap/iterateCollections.ts
@@ -42,6 +42,7 @@ export function iterateCollections({
     addToImportMap(collection.admin?.components?.edit?.PublishButton)
     addToImportMap(collection.admin?.components?.edit?.SaveButton)
     addToImportMap(collection.admin?.components?.edit?.SaveDraftButton)
+    addToImportMap(collection.admin?.components?.edit?.Status)
     addToImportMap(collection.admin?.components?.edit?.Upload)
 
     if (collection.upload?.admin?.components?.controls) {
diff --git a/packages/payload/src/bin/generateImportMap/iterateGlobals.ts b/packages/payload/src/bin/generateImportMap/iterateGlobals.ts
@@ -35,6 +35,7 @@ export function iterateGlobals({
     addToImportMap(global.admin?.components?.elements?.PublishButton)
     addToImportMap(global.admin?.components?.elements?.SaveButton)
     addToImportMap(global.admin?.components?.elements?.SaveDraftButton)
+    addToImportMap(global.admin?.components?.elements?.Status)
 
     if (global.admin?.components?.views?.edit) {
       for (const editViewConfig of Object.values(global.admin?.components?.views?.edit)) {
diff --git a/packages/payload/src/collections/config/types.ts b/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, ViewTypes } from '../../admin/types.js'
+import type { CustomStatus, CustomUpload, ViewTypes } from '../../admin/types.js'
 import type { Arguments as MeArguments } from '../../auth/operations/me.js'
 import type {
   Arguments as RefreshArguments,
@@ -370,6 +370,10 @@ export type CollectionAdminOptions = {
        * + autosave must be disabled
        */
       SaveDraftButton?: CustomComponent
+      /**
+       * Replaces the "Status" section
+       */
+      Status?: CustomStatus
       /**
        * Replaces the "Upload" section
        * + upload must be enabled
diff --git a/packages/payload/src/globals/config/types.ts b/packages/payload/src/globals/config/types.ts
@@ -7,6 +7,7 @@ import type {
   CustomPublishButton,
   CustomSaveButton,
   CustomSaveDraftButton,
+  CustomStatus,
 } from '../../admin/types.js'
 import type {
   Access,
@@ -131,6 +132,10 @@ export type GlobalAdminOptions = {
        * + autosave must be disabled
        */
       SaveDraftButton?: CustomSaveDraftButton
+      /**
+       * Replaces the "Status" section
+       */
+      Status?: CustomStatus
     }
     views?: {
       /**
diff --git a/packages/ui/src/elements/DocumentControls/index.tsx b/packages/ui/src/elements/DocumentControls/index.tsx
@@ -49,6 +49,7 @@ export const DocumentControls: React.FC<{
     readonly PublishButton?: React.ReactNode
     readonly SaveButton?: React.ReactNode
     readonly SaveDraftButton?: React.ReactNode
+    readonly Status?: React.ReactNode
   }
   readonly data?: Data
   readonly disableActions?: boolean
@@ -85,6 +86,7 @@ export const DocumentControls: React.FC<{
       PublishButton: CustomPublishButton,
       SaveButton: CustomSaveButton,
       SaveDraftButton: CustomSaveDraftButton,
+      Status: CustomStatus,
     } = {},
     data,
     disableActions,
@@ -210,7 +212,7 @@ export const DocumentControls: React.FC<{
                       .filter(Boolean)
                       .join(' ')}
                   >
-                    <Status />
+                    <RenderCustomComponent CustomComponent={CustomStatus} Fallback={<Status />} />
                   </li>
                 )}
                 {hasSavePermission &&
diff --git a/packages/ui/src/views/Edit/index.tsx b/packages/ui/src/views/Edit/index.tsx
@@ -60,6 +60,7 @@ export function DefaultEditView({
   PublishButton,
   SaveButton,
   SaveDraftButton,
+  Status,
   Upload: CustomUpload,
   UploadControls,
 }: DocumentViewClientProps) {
@@ -621,6 +622,7 @@ export function DefaultEditView({
               PublishButton,
               SaveButton,
               SaveDraftButton,
+              Status,
             }}
             data={data}
             disableActions={disableActions || isFolderCollection || isTrashed}
diff --git a/test/admin/collections/CustomDocumentControls.ts b/test/admin/collections/CustomDocumentControls.ts
@@ -0,0 +1,23 @@
+import type { CollectionConfig } from 'payload'
+
+import { customDocumentControlsSlug } from '../slugs.js'
+
+export const CollectionCustomDocumentControls: CollectionConfig = {
+  slug: customDocumentControlsSlug,
+  admin: {
+    components: {
+      edit: {
+        Status: '/components/Status/index.tsx#Status',
+      },
+    },
+  },
+  fields: [
+    {
+      name: 'title',
+      type: 'text',
+    },
+  ],
+  versions: {
+    drafts: true,
+  },
+}
diff --git a/test/admin/components/Status/index.tsx b/test/admin/components/Status/index.tsx
@@ -0,0 +1,11 @@
+'use client'
+
+import React from 'react'
+
+export const Status: React.FC = () => {
+  return (
+    <div className="custom-status" id={'custom-status'}>
+      #custom-status
+    </div>
+  )
+}
diff --git a/test/admin/config.ts b/test/admin/config.ts
@@ -4,6 +4,7 @@ import path from 'path'
 import { buildConfigWithDefaults } from '../buildConfigWithDefaults.js'
 import { Array } from './collections/Array.js'
 import { BaseListFilter } from './collections/BaseListFilter.js'
+import { CollectionCustomDocumentControls } from './collections/CustomDocumentControls.js'
 import { CustomFields } from './collections/CustomFields/index.js'
 import { CustomListDrawer } from './collections/CustomListDrawer/index.js'
 import { CustomViews1 } from './collections/CustomViews1.js'
@@ -34,6 +35,7 @@ import { UseAsTitleGroupField } from './collections/UseAsTitleGroupField.js'
 import { Users } from './collections/Users.js'
 import { Virtuals } from './collections/Virtuals.js'
 import { with300Documents } from './collections/With300Documents.js'
+import { GlobalCustomDocumentControls } from './globals/CustomDocumentControls.js'
 import { CustomGlobalViews1 } from './globals/CustomViews1.js'
 import { CustomGlobalViews2 } from './globals/CustomViews2.js'
 import { Global } from './globals/Global.js'
@@ -178,6 +180,7 @@ export default buildConfigWithDefaults({
     CollectionHidden,
     CollectionNotInView,
     CollectionNoApiView,
+    CollectionCustomDocumentControls,
     CustomViews1,
     CustomViews2,
     ReorderTabs,
@@ -209,6 +212,7 @@ export default buildConfigWithDefaults({
     GlobalNotInView,
     GlobalNoApiView,
     Global,
+    GlobalCustomDocumentControls,
     CustomGlobalViews1,
     CustomGlobalViews2,
     GlobalGroup1A,
diff --git a/test/admin/e2e/document-view/e2e.spec.ts b/test/admin/e2e/document-view/e2e.spec.ts
@@ -29,7 +29,9 @@ import {
   overriddenDefaultRouteTabLabel,
 } from '../../shared.js'
 import {
+  customDocumentControlsSlug,
   customFieldsSlug,
+  customGlobalDocumentControlsSlug,
   customGlobalViews2GlobalSlug,
   customViews2CollectionSlug,
   editMenuItemsSlug,
@@ -73,6 +75,7 @@ describe('Document View', () => {
   let globalURL: AdminUrlUtil
   let serverURL: string
   let customViewsURL: AdminUrlUtil
+  let customDocumentControlsURL: AdminUrlUtil
   let customFieldsURL: AdminUrlUtil
   let placeholderURL: AdminUrlUtil
   let collectionCustomViewPathId: string
@@ -93,6 +96,7 @@ describe('Document View', () => {
     postsUrl = new AdminUrlUtil(serverURL, postsCollectionSlug)
     globalURL = new AdminUrlUtil(serverURL, globalSlug)
     customViewsURL = new AdminUrlUtil(serverURL, customViews2CollectionSlug)
+    customDocumentControlsURL = new AdminUrlUtil(serverURL, customDocumentControlsSlug)
     customFieldsURL = new AdminUrlUtil(serverURL, customFieldsSlug)
     placeholderURL = new AdminUrlUtil(serverURL, placeholderCollectionSlug)
     editMenuItemsURL = new AdminUrlUtil(serverURL, editMenuItemsSlug)
@@ -541,6 +545,38 @@ describe('Document View', () => {
     })
   })
 
+  describe('collection — custom document controls', () => {
+    test('should render status component', async () => {
+      await navigateToDoc(page, postsUrl)
+      const statusComponent = page.locator('.doc-controls__status > .status')
+      await expect(statusComponent).toBeVisible()
+      await expect(statusComponent).toContainText('Status: Draft')
+    })
+
+    test('should render custom status component', async () => {
+      await navigateToDoc(page, customDocumentControlsURL)
+      const statusComponent = page.locator('#custom-status')
+      await expect(statusComponent).toBeVisible()
+      await expect(statusComponent).toContainText('#custom-status')
+    })
+  })
+
+  describe('global — custom document controls', () => {
+    test('should render status component', async () => {
+      await page.goto(globalURL.global(globalSlug))
+      const statusComponent = page.locator('.doc-controls__status > .status')
+      await expect(statusComponent).toBeVisible()
+      await expect(statusComponent).toContainText('Status: Draft')
+    })
+
+    test('should render custom status component', async () => {
+      await page.goto(globalURL.global(customGlobalDocumentControlsSlug))
+      const statusComponent = page.locator('#custom-status')
+      await expect(statusComponent).toBeVisible()
+      await expect(statusComponent).toContainText('#custom-status')
+    })
+  })
+
   describe('custom fields', () => {
     test('should render custom field component', async () => {
       await page.goto(customFieldsURL.create)
diff --git a/test/admin/globals/CustomDocumentControls.ts b/test/admin/globals/CustomDocumentControls.ts
@@ -0,0 +1,23 @@
+import type { GlobalConfig } from 'payload'
+
+import { customGlobalDocumentControlsSlug } from '../slugs.js'
+
+export const GlobalCustomDocumentControls: GlobalConfig = {
+  slug: customGlobalDocumentControlsSlug,
+  admin: {
+    components: {
+      elements: {
+        Status: '/components/Status/index.tsx#Status',
+      },
+    },
+  },
+  fields: [
+    {
+      name: 'title',
+      type: 'text',
+    },
+  ],
+  versions: {
+    drafts: true,
+  },
+}
diff --git a/test/admin/payload-types.ts b/test/admin/payload-types.ts
diff --git a/test/admin/seed.ts b/test/admin/seed.ts
diff --git a/test/admin/slugs.ts b/test/admin/slugs.ts

Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,3 @@`
	`1`	`+import type { CustomComponent } from '../../config/types.js'`
	`2`	`+`
	`3`	`+export type CustomStatus = CustomComponent`