Swap in your own React components

While designing the Payload Admin panel, we determined it should be as minimal and straightforward as possible to allow easy customization and control. There are many times where you may want to completely control how a whole view or a field works. You might even want to add in new views entirely. In order for Payload to support this level of customization without introducing versioning / future-proofing issues, Payload provides for a pattern to supply your own React components via your Payload config.

To swap in your own React component, first, consult the list of available component overrides below. Determine the scope that corresponds to what you are trying to accomplish, and then author your React component accordingly.

Base Component Overrides

You can override a set of admin panel-wide components by providing a component to your base Payload config's admin.components property. The following options are available:

Path	Description
`Nav`	Contains the sidebar / mobile menu in its entirety.
`BeforeNavLinks`	Array of components to inject into the built-in Nav, before the links themselves.
`AfterNavLinks`	Array of components to inject into the built-in Nav, after the links.
`BeforeDashboard`	Array of components to inject into the built-in Dashboard, before the default dashboard contents.
`AfterDashboard`	Array of components to inject into the built-in Dashboard, after the default dashboard contents. Demo
`BeforeLogin`	Array of components to inject into the built-in Login, before the default login form.
`AfterLogin`	Array of components to inject into the built-in Login, after the default login form.
`logout.Button`	A custom React component.
`graphics.Icon`	Used as a graphic within the `Nav` component. Often represents a condensed version of a full logo.
`graphics.Logo`	The full logo to be used in contexts like the `Login` view.
`providers`	Define your own provider components that will wrap the Payload Admin UI. More
`actions`	Array of custom components to be rendered in the Payload Admin UI header, providing additional interactivity and functionality.
`views`	Override or create new views within the Payload Admin UI. More

Here is a full example showing how to swap some of these components for your own.

payload.config.js

1import { buildConfig } from 'payload/config'
2
3import {
MyCustomNav,
MyCustomLogo,
MyCustomIcon,
MyCustomAccount,
MyCustomDashboard,
MyProvider,
MyCustomAdminAction,
11} from './customComponents'
12
13export default buildConfig({
admin: {
  components: {
    Nav: MyCustomNav,
    graphics: {
      Icon: MyCustomIcon,
      Logo: MyCustomLogo,
    },
    actions: [MyCustomAdminAction],
    views: {
      Account: MyCustomAccount,
      Dashboard: MyCustomDashboard,
    },
    providers: [MyProvider],
  },
},
29})

Views

You can easily swap entire views with your own by using the admin.components.views property. At the root level, Payload renders the following views by default, all of which can be overridden:

Property	Description
`Account`	The Account view is used to show the currently logged in user's Account page.
`Dashboard`	The main landing page of the Admin panel.

To swap out any of these views, simply pass in your custom component to the admin.components.views property of your Payload config. For example:

1// payload.config.ts
2{
// ...
admin: {
  components: {
    views: {
      Account: MyCustomAccountView,
      Dashboard: MyCustomDashboardView,
    },
  },
},
12}

For more granular control, pass a configuration object instead. Each view corresponds to its own <Route /> component in React Router v5. Payload exposes all of the properties of React Router:

Property	Description
`Component` *	Pass in the component that should be rendered when a user navigates to this route.
`path` *	React Router `path`. See the React Router docs for more info.
`exact`	React Router `exact` property. More
`strict`	React Router `strict` property. More
`sensitive`	React Router `sensitive` property. More

* An asterisk denotes that a property is required.

Adding new views

To add a new view to the Admin Panel, simply add another key to the views object with at least a path and Component property. For example:

1// payload.config.ts
2{
// ...
admin: {
  components: {
    views: {
      MyCustomView: {
        Component: MyCustomView,
        path: '/my-custom-view',
      },
    },
  },
},
14}

For more examples regarding how to customize components, look at the following examples.

For help on how to build your own custom view components, see building a custom view component.

Collections

You can override components on a collection-by-collection basis via the admin.components property.

Path	Description
`BeforeList`	Array of components to inject before the built-in List view
`BeforeListTable`	Array of components to inject before the built-in List view's table
`AfterList`	Array of components to inject after the built-in List view
`AfterListTable`	Array of components to inject after the built-in List view's table
`edit.SaveButton`	Replace the default `Save` button with a custom component. Drafts must be disabled
`edit.SaveDraftButton`	Replace the default `Save Draft` button with a custom component. Drafts must be enabled and autosave must be disabled.
`edit.PublishButton`	Replace the default `Publish` button with a custom component. Drafts must be enabled.
`edit.PreviewButton`	Replace the default `Preview` button with a custom component.
`views`	Override or create new views within the Payload Admin UI. More

Here is a full example showing how to swap some of these components for your own:

Collection.ts

1import * as React from 'react'
2
3import {
4  CustomSaveButtonProps,
5  CustomSaveDraftButtonProps,
6  CustomPublishButtonType,
7  CustomPreviewButtonProps,
8} from 'payload/types'
9
10export const CustomSaveButton: CustomSaveButtonProps = ({ DefaultButton, label, save }) => {
11  return <DefaultButton label={label} save={save} />
12}
13
14export const CustomSaveDraftButton: CustomSaveDraftButtonProps = ({
15  DefaultButton,
16  disabled,
17  label,
18  saveDraft,
19}) => {
20  return <DefaultButton label={label} disabled={disabled} saveDraft={saveDraft} />
21}
22
23export const CustomPublishButton: CustomPublishButtonType = ({
24  DefaultButton,
25  disabled,
26  label,
27  publish,
28}) => {
29  return <DefaultButton label={label} disabled={disabled} publish={publish} />
30}
31
32export const CustomPreviewButton: CustomPreviewButtonProps = ({
33  DefaultButton,
34  disabled,
35  label,
36  preview,
37}) => {
38  return <DefaultButton label={label} disabled={disabled} preview={preview} />
39}
40
41export const MyCollection: SanitizedCollectionConfig = {
42  slug: 'my-collection',
43  admin: {
44    components: {
45      edit: {
46        SaveButton: CustomSaveButton,
47        SaveDraftButton: CustomSaveDraftButton,
48        PublishButton: CustomPublishButton,
49        PreviewButton: CustomPreviewButton,
50      },
51    },
52  }
53}

Collection views

To swap out entire views on collections, you can use the admin.components.views property on the collection's config. Payload renders the following views by default, all of which can be overridden:

Property	Description
`Edit`	The Edit view is used to edit a single document for a given collection.
`List`	The List view is used to show a list of documents for a given collection.

To swap out any of these views, simply pass in your custom component to the admin.components.views property of your Payload config. This will replace the entire view, including the page breadcrumbs, title, tabs, etc, as well as all nested routes.

1// Collection.ts
2{
// ...
admin: {
  components: {
    views: {
      Edit: MyCustomEditView,
      List: MyCustomListView,
    },
  },
},
12}

For help on how to build your own custom view components, see building a custom view component.

Customizing Nested Views within 'Edit' in Collections

The Edit view in collections consists of several nested views, each serving a unique purpose. You can customize these nested views using the admin.components.views.Edit property in the collection's configuration. This approach allows you to replace specific nested views while keeping the overall structure of the Edit view intact, including the page breadcrumbs, title, tabs, etc.

Here's an example of how you can customize nested views within the Edit view in collections, including the use of the actions property:

1// Collection.ts
2{
// ...
admin: {
  components: {
    views: {
      Edit: {
        Default: {
          Component: MyCustomDefaultTab,
          actions: [CollectionEditButton], // Custom actions for the default edit view
        },
        API: {
          Component: MyCustomAPIView,
          actions: [CollectionAPIButton], // Custom actions for API view
        },
        LivePreview: {
          Component: MyCustomLivePreviewView,
          actions: [CollectionLivePreviewButton], // Custom actions for Live Preview
        },
        Version: {
          Component: MyCustomVersionView,
          actions: [CollectionVersionButton], // Custom actions for Version view
        },
        Versions: {
          Component: MyCustomVersionsView,
          actions: [CollectionVersionsButton], // Custom actions for Versions view
        },
      },
      List: {
        actions: [CollectionListButton],
      },
    },
  },
},
35}

Adding New Tabs to 'Edit' View

You can also add new tabs to the Edit view by adding another key to the components.views.Edit[key] object with a path and Component property. See Custom Tabs for more information.

Globals

As with Collections, you can override components on a global-by-global basis via the admin.components property.

Path	Description
`elements.SaveButton`	Replace the default `Save` button with a custom component. Drafts must be disabled
`elements.SaveDraftButton`	Replace the default `Save Draft` button with a custom component. Drafts must be enabled and autosave must be disabled.
`elements.PublishButton`	Replace the default `Publish` button with a custom component. Drafts must be enabled.
`elements.PreviewButton`	Replace the default `Preview` button with a custom component.
`views`	Override or create new views within the Payload Admin UI. More

Global views

To swap out views for globals, you can use the admin.components.views property on the global's config. Payload renders the following views by default, all of which can be overridden:

Property	Description
`Edit`	The Edit view is used to edit a single document for a given Global.

1// Global.ts
2{
// ...
admin: {
  components: {
    views: {
      Edit: MyCustomEditView,
    },
  },
},
11}

For help on how to build your own custom view components, see building a custom view component.

Customizing Nested Views within 'Edit' in Globals

Similar to collections, Globals allow for detailed customization within the Edit view. This includes the ability to swap specific nested views while maintaining the overall structure of the Edit view. You can use the admin.components.views.Edit property in the Globals configuration to achieve this, and this will only replace the nested view, leaving the page breadcrumbs, title, and tabs intact.

Here's how you can customize nested views within the Edit view in Globals, including the use of the actions property:

1// Global.ts
2{
// ...
admin: {
  components: {
    views: {
      Edit: {
        Default: {
          Component: MyCustomGlobalDefaultTab,
          actions: [GlobalEditButton], // Custom actions for the default edit view
        },
        API: {
          Component: MyCustomGlobalAPIView,
          actions: [GlobalAPIButton], // Custom actions for API view
        },
        LivePreview: {
          Component: MyCustomGlobalLivePreviewView,
          actions: [GlobalLivePreviewButton], // Custom actions for Live Preview
        },
        Version: {
          Component: MyCustomGlobalVersionView,
          actions: [GlobalVersionButton], // Custom actions for Version view
        },
        Versions: {
          Component: MyCustomGlobalVersionsView,
          actions: [GlobalVersionsButton], // Custom actions for Versions view
        },
      },
    },
  },
},
32}

You can also add new tabs to the Edit view by adding another key to the components.views.Edit[key] object with a path and Component property. See Custom Tabs for more information.

Custom Tabs

You can easily swap individual collection or global edit views. To do this, pass an object to the admin.components.views.Edit property of the config. Payload renders the following views by default, all of which can be overridden:

Property	Description
`Default`	The Default view is the primary view in which your document is edited.
`Versions`	The Versions view is used to view the version history of a single document. More details
`Version`	The Version view is used to view a single version of a single document for a given collection. More details.
`API`	The API view is used to display the REST API JSON response for a given document.
`LivePreview`	The LivePreview view is used to display the Live Preview interface. More details

Here is an example:

1// Collection.ts or Global.ts
2export const MyCollection: SanitizedCollectionConfig = {
slug: 'my-collection',
admin: {
  components: {
    views: {
      Edit: { // You can also define `components.views.Edit` as a component, this will override _all_ nested views
        Default: MyCustomDefaultTab,
        Versions: MyCustomVersionsTab,
        Version: MyCustomVersionTab,
        API: MyCustomAPITab,
        LivePreview: MyCustomLivePreviewTab,
      },
    },
  },
},
17}

To add a new tab to the Edit view, simply add another key to components.views.Edit[key] with at least a path and Component property. For example:

1// `Collection.ts` or `Global.ts`
2export const MyCollection: SanitizedCollectionConfig = {
slug: 'my-collection',
admin: {
  components: {
    views: {
      Edit: {
        MyCustomTab: {
          Component: MyCustomTab,
          path: '/my-custom-tab',
          // You an swap the entire tab component out for your own
          Tab: MyCustomTab
        },
        AnotherCustomView: {
          Component: AnotherCustomView,
          path: '/another-custom-view',
          // Or you can use the default tab component and just pass in your own label and href
          Tab: {
            label: 'Another Custom View',
            href: '/another-custom-view',
          }
        },
      },
    },
  },
},
27}

Building a custom view component

Your custom view components will be given all the props that a React Router <Route /> typically would receive, as well as two props from Payload:

Prop	Description
`user`	The currently logged in user. Will be `null` if no user is logged in.
`canAccessAdmin` *	If the currently logged in user is allowed to access the admin panel or not.

Example

You can find examples of custom views in the Payload source code /test/admin/components/views folder. There, you'll find two custom views:

A custom view that uses the DefaultTemplate, which is the built-in Payload template that displays the sidebar and "eyebrow nav"
A custom view that uses the MinimalTemplate - which is just a centered template used for things like logging in or out

To see how to pass in your custom views to create custom views of your own, take a look at the admin.components.views property of the Payload test admin config.

Fields

All Payload fields support the ability to swap in your own React components. So, for example, instead of rendering a default Text input, you might need to render a color picker that provides the editor with a custom color picker interface to restrict the data entered to colors only.

Fields support the following custom components:

Component	Description
`Filter`	Override the text input that is presented in the `List` view when a user is filtering documents by the customized field.
`Cell`	Used in the `List` view's table to represent a table-based preview of the data stored in the field. More
`Field`	Swap out the field itself within all `Edit` views. More

As an alternative to replacing the entire Field component, you may want to keep the majority of the default Field component and only swap components within. This allows you to replace the Label or Error within a field component or add additional components inside the field with beforeInput or afterInput. beforeInput and afterInput are allowed in any fields that don't contain other fields, except UI and Rich Text.

Component	Description
`Label`	Override the default Label in the Field Component. More
`Error`	Override the default Error in the Field Component. More
`beforeInput`	An array of elements that will be added before `input`/`textarea` elements. More
`afterInput`	An array of elements that will be added after `input`/`textarea` elements. More

Cell Component

These are the props that will be passed to your custom Cell to use in your own components.

Property	Description
`field`	An object that includes the field configuration.
`colIndex`	A unique number for the column in the list.
`collection`	An object with the config of the collection that the field is in.
`cellData`	The data for the field that the cell represents.
`rowData`	An object with all the field values for the row.

Example

1import React from 'react'
2import type { Props } from 'payload/components/views/Cell'
3import './index.scss'
4
5const baseClass = 'custom-cell'
6
7const CustomCell: React.FC<Props> = (props) => {
8  const { field, colIndex, collection, cellData, rowData } = props
9
10  return <span className={baseClass}>{cellData}</span>
11}

Field Component

When writing your own custom components you can make use of a number of hooks to set data, get reactive changes to other fields, get the id of the document or interact with a context from a custom provider.

Sending and receiving values from the form

When swapping out the Field component, you'll be responsible for sending and receiving the field's value from the form itself. To do so, import the useField hook as follows:

1import { useField } from 'payload/components/forms'
2
3const CustomTextField: React.FC<{ path: string }> = ({ path }) => {
4  const { value, setValue } = useField<string>({ path })
5
6
7  return <input onChange={(e) => setValue(e.target.value)} value={value} />
8}

Label Component

These are the props that will be passed to your custom Label.

Property	Description
`htmlFor`	Property used to set `for` attribute for label.
`label`	Label value provided in field, it can be used with i18n.
`required`	A boolean value that represents if the field is required or not.

Example

1import React from 'react'
2import { useTranslation } from 'react-i18next'
3
4import { getTranslation } from 'payload/utilities/getTranslation'
5
6type Props = {
7  htmlFor?: string
8  label?: Record<string, string> | false | string
9  required?: boolean
10}
11
12const CustomLabel: React.FC<Props> = (props) => {
13  const { htmlFor, label, required = false } = props
14
15  const { i18n } = useTranslation()
16
17  if (label) {
18    return (<span>
19      {getTranslation(label, i18n)}
20      {required && <span className="required">*</span>}
21    </span>);
22  }
23
24  return null
25}

Error Component

These are the props that will be passed to your custom Error.

Property	Description
`message`	The error message.
`showError`	A boolean value that represents if the error should be shown.

Example

1import React from 'react'
2
3type Props = {
4  message: string
5  showError?: boolean
6}
7
8const CustomError: React.FC<Props> = (props) => {
9  const { message, showError } = props
10
11  if (showError) {
12    return <p style={{color: 'red'}}>{message}</p>
13  } else return null;
14}

afterInput and beforeInput

With these properties you can add multiple components before and after the input element. For example, you can add an absolutely positioned button to clear the current field value.

Example

1import React from 'react'
2import { Field } from 'payload/types'
3
4import './style.scss'
5
6const ClearButton: React.FC = () => {
7  return <button onClick={() => {/* ... */}}>X</button>
8}
9
10const titleField: Field = {
11  name: 'title',
12  type: 'text',
13  admin: {
14    components: {
15      afterInput: [ClearButton]
16    }
17  }
18}
19
20export default titleField;

Custom providers

As your admin customizations gets more complex you may want to share state between fields or other components. You can add custom providers to add your own context to any Payload app for use in other custom components within the admin panel. Within your config add admin.components.providers, these can be used to share context or provide other custom functionality. Read the React context docs to learn more.

Styling Custom Components

Payload exports its SCSS variables and mixins for reuse in your own custom components. This is helpful in cases where you might want to style a custom input similarly to Payload's built-in styling, so it blends more thoroughly into the existing admin UI.

To make use of Payload SCSS variables / mixins to use directly in your own components, you can import them as follows:

1@import '~payload/scss';

Getting the current language

When developing custom components you can support multiple languages to be consistent with Payload's i18n support. The best way to do this is to add your translation resources to the i18n configuration and import useTranslation from react-i18next in your components.

For example:

1import { useTranslation } from 'react-i18next'
2
3const CustomComponent: React.FC = () => {
4  const { t, i18n } = useTranslation('namespace1')
5
6  return (
7    <ul>
8      <li>{t('key', { variable: 'value' })}</li>
9      <li>{t('namespace2:key', { variable: 'value' })}</li>
10      <li>{i18n.language}</li>
11    </ul>
12  )
13}

Getting the current locale

In any custom component you can get the selected locale with useLocale hook. useLocale returns the full locale object, consisting of a label, rtl(right-to-left) property, and then code. Here is a simple example:

1import { useLocale } from 'payload/components/utilities'
2
3const Greeting: React.FC = () => {
4  const locale = useLocale()
5
6  const trans = {
7    en: 'Hello',
8    es: 'Hola',
9  }
10
11  return <span> {trans[locale.code]} </span>
12}

See what others are building with Payload.

"Payload has transformed the way our clients manage content. It's an indispensable tool for any modern agency."

Deploy your entire stack in one place with Payload Cloud.

Microsoft chose Payload to tell the world about AI.

Swap in your own React components

Base Component Overrides

Views

Adding new views

Collections

Collection views

Globals

Global views

Custom Tabs

Building a custom view component

Example

Fields

Cell Component

Example

Field Component

Sending and receiving values from the form

Label Component

Example

Error Component

Example

afterInput and beforeInput

Example

Custom providers

Styling Custom Components

Getting the current language

Getting the current locale

React Hooks

Related Help Topics