Code-based nature means you can build on top of it to power anything.
Resources
DocumentationExamplesTemplatesGitHubBlog
Community
RoadmapDiscordCommunity Help
Payload Cloud

Deploy your entire stack in one place with Payload Cloud.

LoginCloud Pricing
It’s time to take back your content infrastructure.
Schedule a Demo
Enterprise Features
SSOPublishing WorkflowsVisual EditorStatic A/B testingAI features
Customer Stories
MicrosoftBlue OriginHello BelloMythical SocietyTekton
Featured Customer Story

Microsoft chose Payload to tell the world about AI.

Read the case study
New projectLogin
New projectLogin

Customizing Views

Views are the individual pages that make up the Admin Panel, such as the Dashboard, List, and Edit views. One of the most powerful ways to customize the Admin Panel is to create Custom Views. These are Custom Components that can either replace built-in views or can be entirely new.

There are four types of views within the Admin Panel:

To swap in your own Custom Views, 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 Views

Root Views are the main views of the Admin Panel. These are views that are scoped directly under the /admin route, such as the Dashboard or Account views.

To easily swap Root Views with your own, or to create entirely new ones, use the admin.components.views property of your root Payload Config:

1
import { buildConfig } from 'payload'
2
3
const config = buildConfig({
4
// ...
5
admin: {
6
components: {
7
views: {
8
customView: {
9
Component: '/path/to/MyCustomView#MyCustomView',
10
path: '/my-custom-view',
11
}
12
},
13
},
14
},
15
})

Your Custom Root Views can optionally use one of the templates that Payload provides. The most common of these is the Default Template which provides the basic layout and navigation. Here is an example of what that might look like:

1
import type { AdminViewProps } from 'payload'
2
3
import { DefaultTemplate } from '@payloadcms/next/templates'
4
import { Gutter } from '@payloadcms/ui'
5
import React from 'react'
6
7
export const MyCustomView: React.FC<AdminViewProps> = ({
8
initPageResult,
9
params,
10
searchParams,
11
}) => {
12
return (
13
<DefaultTemplate
14
i18n={initPageResult.req.i18n}
15
locale={initPageResult.locale}
16
params={params}
17
payload={initPageResult.req.payload}
18
permissions={initPageResult.permissions}
19
searchParams={searchParams}
20
user={initPageResult.req.user || undefined}
21
visibleEntities={initPageResult.visibleEntities}
22
>
23
<Gutter>
24
<h1>Custom Default Root View</h1>
25
<br />
26
<p>This view uses the Default Template.</p>
27
</Gutter>
28
</DefaultTemplate>
29
)
30
}

For details on how to build Custom Views, including all available props, see Building Custom Views.

The following options are available:

PropertyDescription
accountThe Account view is used to show the currently logged in user's Account page.
dashboardThe main landing page of the Admin Panel.

For more granular control, pass a configuration object instead. Payload exposes the following properties for each view:

PropertyDescription
Component *Pass in the component path that should be rendered when a user navigates to this route.
path *Any valid URL path or array of paths that path-to-regexp understands.
exactBoolean. When true, will only match if the path matches the usePathname() exactly.
strictWhen true, a path that has a trailing slash will only match a location.pathname with a trailing slash. This has no effect when there are additional URL segments in the pathname.
sensitiveWhen true, will match if the path is case sensitive.
metaPage metadata overrides to apply to this view within the Admin Panel. More details.

* An asterisk denotes that a property is required.

Adding New Views

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

1
import { buildConfig } from 'payload'
2
3
const config = buildConfig({
4
// ...
5
admin: {
6
components: {
7
views: {
8
myCustomView: {
9
Component: '/path/to/MyCustomView#MyCustomViewComponent',
10
path: '/my-custom-view',
11
},
12
},
13
},
14
},
15
})

The above example shows how to add a new Root View, but the pattern is the same for Collection Views, Global Views, and Document Views. For help on how to build your own Custom Views, see Building Custom Views.

Collection Views

Collection Views are views that are scoped under the /collections route, such as the Collection List and Document Edit views.

To easily swap out Collection Views with your own, or to create entirely new ones, use the admin.components.views property of your Collection Config:

1
import type { SanitizedCollectionConfig } from 'payload'
2
3
export const MyCollectionConfig: SanitizedCollectionConfig = {
4
// ...
5
admin: {
6
components: {
7
views: {
8
edit: {
9
root: {
10
Component: '/path/to/MyCustomEditView',
11
}
12
// other options include:
13
// default
14
// versions
15
// version
16
// api
17
// livePreview
18
// [key: string]
19
// See "Document Views" for more details
20
},
21
list: {
22
Component: '/path/to/MyCustomListView',
23
}
24
},
25
},
26
},
27
}

For details on how to build Custom Views, including all available props, see Building Custom Views.

The following options are available:

PropertyDescription
editThe Edit View is used to edit a single document for any given Collection. More details.
listThe List View is used to show a list of documents for any given Collection.

Global Views

Global Views are views that are scoped under the /globals route, such as the Document Edit View.

To easily swap out Global Views with your own or create entirely new ones, use the admin.components.views property in your Global Config:

1
import type { SanitizedGlobalConfig } from 'payload'
2
3
export const MyGlobalConfig: SanitizedGlobalConfig = {
4
// ...
5
admin: {
6
components: {
7
views: {
8
edit: {
9
root: {
10
Component: '/path/to/MyCustomEditView',
11
}
12
// other options include:
13
// default
14
// versions
15
// version
16
// api
17
// livePreview
18
// [key: string]
19
},
20
},
21
},
22
},
23
}

For details on how to build Custom Views, including all available props, see Building Custom Views.

The following options are available:

PropertyDescription
editThe Edit View is used to edit a single document for any given Global. More details.

Document Views

Document Views are views that are scoped under the /collections/:collectionSlug/:id or the /globals/:globalSlug route, such as the Edit View or the API View. All Document Views keep their overall structure across navigation changes, such as their title and tabs, and replace only the content below.

To easily swap out Document Views with your own, or to create entirely new ones, use the admin.components.views.Edit[key] property in your Collection Config or Global Config:

1
import type { SanitizedCollectionConfig } from 'payload'
2
3
export const MyCollectionOrGlobalConfig: SanitizedCollectionConfig = {
4
// ...
5
admin: {
6
components: {
7
views: {
8
edit: {
9
api: {
10
Component: '/path/to/MyCustomAPIViewComponent',
11
},
12
},
13
},
14
},
15
},
16
}

For details on how to build Custom Views, including all available props, see Building Custom Views.

The following options are available:

PropertyDescription
rootThe Root View overrides all other nested views and routes. No document controls or tabs are rendered when this key is set.
defaultThe Default View is the primary view in which your document is edited. It is rendered within the "Edit" tab.
versionsThe Versions View is used to navigate the version history of a single document. It is rendered within the "Versions" tab. More details.
versionThe Version View is used to edit a single version of a document. It is rendered within the "Version" tab. More details.
apiThe API View is used to display the REST API JSON response for a given document. It is rendered within the "API" tab.
livePreviewThe LivePreview view is used to display the Live Preview interface. It is rendered within the "Live Preview" tab. More details.

Document Tabs

Each Document View can be given a new tab in the Edit View, if desired. Tabs are highly configurable, from as simple as changing the label to swapping out the entire component, they can be modified in any way. To add or customize tabs in the Edit View, use the tab key:

1
import type { SanitizedCollectionConfig } from 'payload'
2
3
export const MyCollection: SanitizedCollectionConfig = {
4
slug: 'my-collection',
5
admin: {
6
components: {
7
views: {
8
edit: {
9
myCustomTab: {
10
Component: '/path/to/MyCustomTab',
11
path: '/my-custom-tab',
12
tab: {
13
Component: '/path/to/MyCustomTabComponent'
14
}
15
},
16
anotherCustomTab: {
17
Component: '/path/to/AnotherCustomView',
18
path: '/another-custom-view',
19
tab: {
20
label: 'Another Custom View',
21
href: '/another-custom-view',
22
}
23
},
24
},
25
},
26
},
27
},
28
}

Building Custom Views

Custom Views are just Custom Components rendered at the page-level. To understand how to build Custom Views, first review the Building Custom Components guide. Once you have a Custom Component ready, you can use it as a Custom View.

1
import type { SanitizedCollectionConfig } from 'payload'
2
3
export const MyCollectionConfig: SanitizedCollectionConfig = {
4
// ...
5
admin: {
6
components: {
7
views: {
8
edit: {
9
Component: '/path/to/MyCustomView'
10
}
11
},
12
},
13
},
14
}

Your Custom Views will be provided with the following props:

PropDescription
initPageResultAn object containing req, payload, permissions, etc.
clientConfigThe Client Config object. More details.
importMapThe import map object.
paramsAn object containing the Dynamic Route Parameters.
searchParamsAn object containing the Search Parameters.
Next

Customizing Fields

On this page
Star on GitHub

Star

Chat on Discord

Discord

online