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 your own routes entirely. In order for Payload to support that 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:

PathDescription
NavContains the sidebar and mobile Nav in its entirety.
views.AccountThe Account view is used to show the currently logged in user's Account page.
views.DashboardThe main landing page of the Admin panel.
graphics.IconUsed as a graphic within the Nav component. Often represents a condensed version of a full logo.
graphics.LogoThe full logo to be used in contexts like the Login view.

Full example:

payload.config.js

import { buildConfig } from 'payload/config';
import { MyCustomNav, MyCustomLogo, MyCustomIcon, MyCustomAccount, MyCustomDashboard } from './customComponents.js';
export default buildConfig({
serverURL: 'http://localhost:3000',
admin: {
components: {
Nav: MyCustomNav,
graphics: {
Icon: MyCustomIcon,
Logo: MyCustomLogo,
},
views: {
Account: MyCustomAccount,
Dashboard: MyCustomDashboard,
}
}
}
})

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

Collections

You can override components on a Collection-by-Collection basis via each Collection's admin property.

PathDescription
views.EditUsed while a document within this Collection is being edited.
views.ListThe List view is used to render a paginated, filterable table of Documents in this Collection.

Globals

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

PathDescription
views.EditUsed while this Global is being edited.

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:

ComponentDescription
FilterOverride the text input that is presented in the List view when a user is filtering documents by the customized field.
CellUsed in the List view's table to represent a table-based preview of the data stored in the field.
FieldSwap out the field itself within all Edit views.

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 useFieldType hook as follows:

import { useFieldType } from 'payload/components/forms';
const CustomTextField = ({ path }) => {
const { value, setValue } = useFieldType({ path });
return (
<input
onChange={(e) => setValue(e.target.value)}
value={value}
/>
)
}

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-ini 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:

@import '~payload/scss';
Next

Customizing CSS & SCSS