Swap in your own React components

The Payload Admin Panel is designed to be as minimal and straightforward as possible to allow for both easy customization and full control over the UI. In order for Payload to support this level of customization, Payload provides a pattern for you to supply your own React components through your Payload Config.

All Custom Components in Payload are React Server Components by default, with the exception of Custom Providers. This enables the use of the Local API directly on the front-end. Custom Components are available for nearly every part of the Admin Panel for extreme granularity and control.

There are four main types of Custom Components in Payload:

To swap in your own Custom Component, consult the list of available components. Determine the scope that corresponds to what you are trying to accomplish, then author your React component(s) accordingly.

Root Components

Root Components are those that effect the Admin Panel generally, such as the logo or the main nav.

To override Root Components, use the admin.components property in your Payload Config:

1
import { buildConfig } from 'payload'
2
3
import { MyCustomLogo } from './MyCustomLogo'
4
5
export default buildConfig({
6
// ...
7
admin: {
8
components: {
9
// ...
10
},
11
},
12
})

For details on how to build Custom Components, see Building Custom Components.

The following options are available:

PathDescription
NavContains the sidebar / mobile menu in its entirety.
beforeNavLinksAn array of Custom Components to inject into the built-in Nav, before the links themselves.
afterNavLinksAn array of Custom Components to inject into the built-in Nav, after the links.
beforeDashboardAn array of Custom Components to inject into the built-in Dashboard, before the default dashboard contents.
afterDashboardAn array of Custom Components to inject into the built-in Dashboard, after the default dashboard contents.
beforeLoginAn array of Custom Components to inject into the built-in Login, before the default login form.
afterLoginAn array of Custom Components to inject into the built-in Login, after the default login form.
logout.ButtonThe button displayed in the sidebar that logs the user out.
graphics.IconThe simplified logo used in contexts like the the Nav component.
graphics.LogoThe full logo used in contexts like the Login view.
providersCustom React Context providers that will wrap the entire Admin Panel. More details.
actionsAn array of Custom Components to be rendered in the header of the Admin Panel, providing additional interactivity and functionality.
viewsOverride or create new views within the Admin Panel. More details.

Custom Providers

As you add more and more Custom Components to your Admin Panel, you may find it helpful to add additional React Context(s). Payload allows you to inject your own context providers in your app so you can export your own custom hooks, etc.

To add a Custom Provider, use the admin.components.providers property in your Payload Config:

1
import { buildConfig } from 'payload'
2
3
import { MyProvider } from './MyProvider'
4
5
export default buildConfig({
6
// ...
7
admin: {
8
components: {
9
providers: [MyProvider],
10
},
11
},
12
})

Then build your Custom Provider as follows:

1
'use client'
2
import React, { createContext, useContext } from 'react'
3
4
const MyCustomContext = React.createContext(myCustomValue)
5
6
export const MyProvider: React.FC = ({ children }) => {
7
return (
8
<MyCustomContext.Provider value={myCustomValue}>
9
{children}
10
</MyCustomContext.Provider>
11
)
12
}
13
14
export const useMyCustomContext = () => useContext(MyCustomContext)

Building Custom Components

All Custom Components in Payload are React Server Components by default, with the exception of Custom Providers. This enables the use of the Local API directly on the front-end, among other things.

To make building Custom Components as easy as possible, Payload automatically provides common props, such as the payload class and the i18n object. This means that when building Custom Components within the Admin Panel, you do not have to get these yourself.

Here is an example:

1
import React from 'react'
2
3
const MyServerComponent = async ({
4
payload
5
}) => {
6
const page = await payload.findByID({
7
collection: 'pages',
8
id: '123',
9
})
10
11
return (
12
<p>{page.title}</p>
13
)
14
}

Each Custom Component receives the following props by default:

PropDescription
payloadThe Payload class.
i18nThe i18n object.

Custom Components also receive various other props that are specific to the context in which the Custom Component is being rendered. For example, Custom Views receive the user prop. For a full list of available props, consult the documentation related to the specific component you are working with.

Client Components

When Building Custom Components, it's still possible to use client-side code such as useState or the window object. To do this, simply add the use client directive at the top of your file. Payload will automatically detect and remove all default, non-serializable props before rendering your component.

1
'use client'
2
import React, { useState } from 'react'
3
4
export const MyClientComponent: React.FC = () => {
5
const [count, setCount] = useState(0)
6
7
return (
8
<button onClick={() => setCount(count + 1)}>
9
Clicked {count} times
10
</button>
11
)
12
}

Accessing the Payload Config

From any Server Component, the Payload Config can be accessed directly from the payload prop:

1
import React from 'react'
2
3
export default async function MyServerComponent({
4
payload: {
5
config
6
}
7
}) {
8
return (
9
<Link href={config.serverURL}>
10
Go Home
11
</Link>
12
)
13
}

But, the Payload Config is non-serializable by design. It is full of custom validation functions, React components, etc. This means that the Payload Config, in its entirety, cannot be passed directly to Client Components.

For this reason, Payload creates a Client Config and passes it into the Config Provider. This is a serializable version of the Payload Config that can be accessed from any Client Component via the useConfig hook:

1
import React from 'react'
2
import { useConfig } from '@payloadcms/ui'
3
4
export const MyClientComponent: React.FC = () => {
5
const { serverURL } = useConfig()
6
7
return (
8
<Link href={serverURL}>
9
Go Home
10
</Link>
11
)
12
}

Using Hooks

To make it easier to build your Custom Components, you can use Payload's built-in React Hooks in any Client Component. For example, you might want to interact with one of Payload's many React Contexts:

1
'use client'
2
import React from 'react'
3
import { useDocumentInfo } from '@payloadcms/ui'
4
5
export const MyClientComponent: React.FC = () => {
6
const { slug } = useDocumentInfo()
7
8
return (
9
<p>{`Entity slug: ${slug}`}</p>
10
)
11
}

Getting the Current Language

All Custom Components can support multiple languages to be consistent with Payload's Internationalization. To do this, first add your translation resources to the I18n Config.

From any Server Component, you can translate resources using the getTranslation function from @payloadcms/translations. All Server Components automatically receive the i18n object as a prop by default.

1
import React from 'react'
2
import { getTranslation } from '@payloadcms/translations'
3
4
export default async function MyServerComponent({ i18n }) {
5
const translatedTitle = getTranslation(myTranslation, i18n)
6
7
return (
8
<p>{translatedTitle}</p>
9
)
10
}

The best way to do this within a Client Component is to import the useTranslation hook from @payloadcms/ui:

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

Getting the Current Locale

All Custom Views can support multiple locales to be consistent with Payload's Localization. They automatically receive the locale object as a prop by default. This can be used to scope API requests, etc.:

1
import React from 'react'
2
3
export default async function MyServerComponent({ payload, locale }) {
4
const localizedPage = await payload.findByID({
5
collection: 'pages',
6
id: '123',
7
locale,
8
})
9
10
return (
11
<p>{localizedPage.title}</p>
12
)
13
}

The best way to do this within a Client Component is to import the useLocale hook from @payloadcms/ui:

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

Styling Custom Components

Payload has a robust CSS Library that you can use to style your Custom Components similarly to Payload's built-in styling. This will ensure that your Custom Components match the existing design system, and so that they automatically adapt to any theme changes that might occur.

To apply custom styles, simply import your own .css or .scss file into your Custom Component:

1
import './index.scss'
2
3
export const MyComponent: React.FC = () => {
4
return (
5
<div className="my-component">
6
My Custom Component
7
</div>
8
)
9
}

Then to colorize your Custom Component's background, for example, you can use the following CSS:

1
.my-component {
2
background-color: var(--theme-elevation-500);
3
}

Payload also exports its SCSS library for reuse which includes mixins, etc. To use this, simply import it as follows into your .scss file:

1
@import '~payload/scss';
2
3
.my-component {
4
@include mid-break {
5
background-color: var(--theme-elevation-900);
6
}
7
}
Next

Customizing Views