440 lines
13 KiB
Plaintext
440 lines
13 KiB
Plaintext
---
|
|
title: Root Components
|
|
label: Root Components
|
|
order: 20
|
|
desc:
|
|
keywords: admin, components, custom, documentation, Content Management System, cms, headless, javascript, node, react, nextjs
|
|
---
|
|
|
|
Root Components are those that affect the [Admin Panel](../admin/overview) at a high-level, such as the logo or the main nav. You can swap out these components with your own [Custom Components](./overview) to create a completely custom look and feel.
|
|
|
|
When combined with [Custom CSS](../admin/customizing-css), you can create a truly unique experience for your users, such as white-labeling the Admin Panel to match your brand.
|
|
|
|
To override Root Components, use the `admin.components` property at the root of your [Payload Config](../configuration/overview):
|
|
|
|
```ts
|
|
import { buildConfig } from 'payload'
|
|
|
|
export default buildConfig({
|
|
// ...
|
|
admin: {
|
|
// highlight-start
|
|
components: {
|
|
// ...
|
|
},
|
|
// highlight-end
|
|
},
|
|
})
|
|
```
|
|
|
|
## Config Options
|
|
|
|
The following options are available:
|
|
|
|
| Path | Description |
|
|
| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
|
| `actions` | An array of Custom Components to be rendered _within_ the header of the Admin Panel, providing additional interactivity and functionality. [More details](#actions). |
|
|
| `afterDashboard` | An array of Custom Components to inject into the built-in Dashboard, _after_ the default dashboard contents. [More details](#afterdashboard). |
|
|
| `afterLogin` | An array of Custom Components to inject into the built-in Login, _after_ the default login form. [More details](#afterlogin). |
|
|
| `afterNavLinks` | An array of Custom Components to inject into the built-in Nav, _after_ the links. [More details](#afternavlinks). |
|
|
| `beforeDashboard` | An array of Custom Components to inject into the built-in Dashboard, _before_ the default dashboard contents. [More details](#beforedashboard). |
|
|
| `beforeLogin` | An array of Custom Components to inject into the built-in Login, _before_ the default login form. [More details](#beforelogin). |
|
|
| `beforeNavLinks` | An array of Custom Components to inject into the built-in Nav, _before_ the links themselves. [More details](#beforenavlinks). |
|
|
| `graphics.Icon` | The simplified logo used in contexts like the `Nav` component. [More details](#graphicsicon). |
|
|
| `graphics.Logo` | The full logo used in contexts like the `Login` view. [More details](#graphicslogo). |
|
|
| `header` | An array of Custom Components to be injected above the Payload header. [More details](#header). |
|
|
| `logout.Button` | The button displayed in the sidebar that logs the user out. [More details](#logoutbutton). |
|
|
| `Nav` | Contains the sidebar / mobile menu in its entirety. [More details](#nav). |
|
|
| `providers` | Custom [React Context](https://react.dev/learn/scaling-up-with-reducer-and-context) providers that will wrap the entire Admin Panel. [More details](./custom-providers). |
|
|
| `views` | Override or create new views within the Admin Panel. [More details](./custom-views). |
|
|
|
|
_For details on how to build Custom Components, see [Building Custom Components](./overview#building-custom-components)._
|
|
|
|
<Banner type="success">
|
|
**Note:** You can also use set [Collection
|
|
Components](../configuration/collections#custom-components) and [Global
|
|
Components](../configuration/globals#custom-components) in their respective
|
|
configs.
|
|
</Banner>
|
|
|
|
## Components
|
|
|
|
### actions
|
|
|
|
Actions are rendered within the header of the Admin Panel. Actions are typically used to display buttons that add additional interactivity and functionality, although they can be anything you'd like.
|
|
|
|
To add an action, use the `actions` property in your `admin.components` config:
|
|
|
|
```ts
|
|
import { buildConfig } from 'payload'
|
|
|
|
export default buildConfig({
|
|
// ...
|
|
admin: {
|
|
// highlight-start
|
|
components: {
|
|
actions: ['/path/to/your/component'],
|
|
},
|
|
// highlight-end
|
|
},
|
|
})
|
|
```
|
|
|
|
Here is an example of a simple Action component:
|
|
|
|
```tsx
|
|
export default function MyCustomAction() {
|
|
return (
|
|
<button onClick={() => alert('Hello, world!')}>
|
|
This is a custom action component
|
|
</button>
|
|
)
|
|
}
|
|
```
|
|
|
|
<Banner type="success">
|
|
**Note:** You can also use add Actions to the [Edit View](./edit-view) and
|
|
[List View](./list-view) in their respective configs.
|
|
</Banner>
|
|
|
|
### beforeDashboard
|
|
|
|
The `beforeDashboard` property allows you to inject Custom Components into the built-in Dashboard, before the default dashboard contents.
|
|
|
|
To add `beforeDashboard` components, use the `admin.components.beforeDashboard` property in your Payload Config:
|
|
|
|
```ts
|
|
import { buildConfig } from 'payload'
|
|
|
|
export default buildConfig({
|
|
// ...
|
|
admin: {
|
|
// highlight-start
|
|
components: {
|
|
beforeDashboard: ['/path/to/your/component'],
|
|
},
|
|
// highlight-end
|
|
},
|
|
})
|
|
```
|
|
|
|
Here is an example of a simple `beforeDashboard` component:
|
|
|
|
```tsx
|
|
export default function MyBeforeDashboardComponent() {
|
|
return <div>This is a custom component injected before the Dashboard.</div>
|
|
}
|
|
```
|
|
|
|
### afterDashboard
|
|
|
|
Similar to `beforeDashboard`, the `afterDashboard` property allows you to inject Custom Components into the built-in Dashboard, _after_ the default dashboard contents.
|
|
|
|
To add `afterDashboard` components, use the `admin.components.afterDashboard` property in your Payload Config:
|
|
|
|
```ts
|
|
import { buildConfig } from 'payload'
|
|
|
|
export default buildConfig({
|
|
// ...
|
|
admin: {
|
|
// highlight-start
|
|
components: {
|
|
afterDashboard: ['/path/to/your/component'],
|
|
},
|
|
// highlight-end
|
|
},
|
|
})
|
|
```
|
|
|
|
Here is an example of a simple `afterDashboard` component:
|
|
|
|
```tsx
|
|
export default function MyAfterDashboardComponent() {
|
|
return <div>This is a custom component injected after the Dashboard.</div>
|
|
}
|
|
```
|
|
|
|
### beforeLogin
|
|
|
|
The `beforeLogin` property allows you to inject Custom Components into the built-in Login view, _before_ the default login form.
|
|
|
|
To add `beforeLogin` components, use the `admin.components.beforeLogin` property in your Payload Config:
|
|
|
|
```ts
|
|
import { buildConfig } from 'payload'
|
|
|
|
export default buildConfig({
|
|
// ...
|
|
admin: {
|
|
// highlight-start
|
|
components: {
|
|
beforeLogin: ['/path/to/your/component'],
|
|
},
|
|
// highlight-end
|
|
},
|
|
})
|
|
```
|
|
|
|
Here is an example of a simple `beforeLogin` component:
|
|
|
|
```tsx
|
|
export default function MyBeforeLoginComponent() {
|
|
return <div>This is a custom component injected before the Login form.</div>
|
|
}
|
|
```
|
|
|
|
### afterLogin
|
|
|
|
Similar to `beforeLogin`, the `afterLogin` property allows you to inject Custom Components into the built-in Login view, _after_ the default login form.
|
|
|
|
To add `afterLogin` components, use the `admin.components.afterLogin` property in your Payload Config:
|
|
|
|
```ts
|
|
import { buildConfig } from 'payload'
|
|
|
|
export default buildConfig({
|
|
// ...
|
|
admin: {
|
|
// highlight-start
|
|
components: {
|
|
afterLogin: ['/path/to/your/component'],
|
|
},
|
|
// highlight-end
|
|
},
|
|
})
|
|
```
|
|
|
|
Here is an example of a simple `afterLogin` component:
|
|
|
|
```tsx
|
|
export default function MyAfterLoginComponent() {
|
|
return <div>This is a custom component injected after the Login form.</div>
|
|
}
|
|
```
|
|
|
|
### beforeNavLinks
|
|
|
|
The `beforeNavLinks` property allows you to inject Custom Components into the built-in [Nav Component](#nav), _before_ the nav links themselves.
|
|
|
|
To add `beforeNavLinks` components, use the `admin.components.beforeNavLinks` property in your Payload Config:
|
|
|
|
```ts
|
|
import { buildConfig } from 'payload'
|
|
|
|
export default buildConfig({
|
|
// ...
|
|
admin: {
|
|
// highlight-start
|
|
components: {
|
|
beforeNavLinks: ['/path/to/your/component'],
|
|
},
|
|
// highlight-end
|
|
},
|
|
})
|
|
```
|
|
|
|
Here is an example of a simple `beforeNavLinks` component:
|
|
|
|
```tsx
|
|
export default function MyBeforeNavLinksComponent() {
|
|
return <div>This is a custom component injected before the Nav links.</div>
|
|
}
|
|
```
|
|
|
|
### afterNavLinks
|
|
|
|
Similar to `beforeNavLinks`, the `afterNavLinks` property allows you to inject Custom Components into the built-in Nav, _after_ the nav links.
|
|
|
|
To add `afterNavLinks` components, use the `admin.components.afterNavLinks` property in your Payload Config:
|
|
|
|
```ts
|
|
import { buildConfig } from 'payload'
|
|
|
|
export default buildConfig({
|
|
// ...
|
|
admin: {
|
|
// highlight-start
|
|
components: {
|
|
afterNavLinks: ['/path/to/your/component'],
|
|
},
|
|
// highlight-end
|
|
},
|
|
})
|
|
```
|
|
|
|
Here is an example of a simple `afterNavLinks` component:
|
|
|
|
```tsx
|
|
export default function MyAfterNavLinksComponent() {
|
|
return <p>This is a custom component injected after the Nav links.</p>
|
|
}
|
|
```
|
|
|
|
### Nav
|
|
|
|
The `Nav` property contains the sidebar / mobile menu in its entirety. Use this property to completely replace the built-in Nav with your own custom navigation.
|
|
|
|
To add a custom nav, use the `admin.components.Nav` property in your Payload Config:
|
|
|
|
```ts
|
|
import { buildConfig } from 'payload'
|
|
|
|
export default buildConfig({
|
|
// ...
|
|
admin: {
|
|
// highlight-start
|
|
components: {
|
|
Nav: '/path/to/your/component',
|
|
},
|
|
// highlight-end
|
|
},
|
|
})
|
|
```
|
|
|
|
Here is an example of a simple `Nav` component:
|
|
|
|
```tsx
|
|
import { Link } from '@payloadcms/ui'
|
|
|
|
export default function MyCustomNav() {
|
|
return (
|
|
<nav>
|
|
<ul>
|
|
<li>
|
|
<Link href="/dashboard">Dashboard</Link>
|
|
</li>
|
|
</ul>
|
|
</nav>
|
|
)
|
|
}
|
|
```
|
|
|
|
### graphics.Icon
|
|
|
|
The `Icon` property is the simplified logo used in contexts like the `Nav` component. This is typically a small, square icon that represents your brand.
|
|
|
|
To add a custom icon, use the `admin.components.graphics.Icon` property in your Payload Config:
|
|
|
|
```ts
|
|
import { buildConfig } from 'payload'
|
|
|
|
export default buildConfig({
|
|
// ...
|
|
admin: {
|
|
// highlight-start
|
|
components: {
|
|
graphics: {
|
|
Icon: '/path/to/your/component',
|
|
},
|
|
},
|
|
// highlight-end
|
|
},
|
|
})
|
|
```
|
|
|
|
Here is an example of a simple `Icon` component:
|
|
|
|
```tsx
|
|
export default function MyCustomIcon() {
|
|
return <img src="/path/to/your/icon.png" alt="My Custom Icon" />
|
|
}
|
|
```
|
|
|
|
### graphics.Logo
|
|
|
|
The `Logo` property is the full logo used in contexts like the `Login` view. This is typically a larger, more detailed representation of your brand.
|
|
|
|
To add a custom logo, use the `admin.components.graphics.Logo` property in your Payload Config:
|
|
|
|
```ts
|
|
import { buildConfig } from 'payload'
|
|
|
|
export default buildConfig({
|
|
// ...
|
|
admin: {
|
|
// highlight-start
|
|
components: {
|
|
graphics: {
|
|
Logo: '/path/to/your/component',
|
|
},
|
|
},
|
|
// highlight-end
|
|
},
|
|
})
|
|
```
|
|
|
|
Here is an example of a simple `Logo` component:
|
|
|
|
```tsx
|
|
export default function MyCustomLogo() {
|
|
return <img src="/path/to/your/logo.png" alt="My Custom Logo" />
|
|
}
|
|
```
|
|
|
|
### header
|
|
|
|
The `header` property allows you to inject Custom Components above the Payload header.
|
|
|
|
Examples of a custom header components might include an announcements banner, a notifications bar, or anything else you'd like to display at the top of the Admin Panel in a prominent location.
|
|
|
|
To add `header` components, use the `admin.components.header` property in your Payload Config:
|
|
|
|
```ts
|
|
import { buildConfig } from 'payload'
|
|
|
|
export default buildConfig({
|
|
// ...
|
|
admin: {
|
|
// highlight-start
|
|
components: {
|
|
header: ['/path/to/your/component'],
|
|
},
|
|
// highlight-end
|
|
},
|
|
})
|
|
```
|
|
|
|
Here is an example of a simple `header` component:
|
|
|
|
```tsx
|
|
export default function MyCustomHeader() {
|
|
return (
|
|
<header>
|
|
<h1>My Custom Header</h1>
|
|
</header>
|
|
)
|
|
}
|
|
```
|
|
|
|
### logout.Button
|
|
|
|
The `logout.Button` property is the button displayed in the sidebar that should log the user out when clicked.
|
|
|
|
To add a custom logout button, use the `admin.components.logout.Button` property in your Payload Config:
|
|
|
|
```ts
|
|
import { buildConfig } from 'payload'
|
|
|
|
export default buildConfig({
|
|
// ...
|
|
admin: {
|
|
// highlight-start
|
|
components: {
|
|
logout: {
|
|
Button: '/path/to/your/component',
|
|
},
|
|
},
|
|
// highlight-end
|
|
},
|
|
})
|
|
```
|
|
|
|
Here is an example of a simple `logout.Button` component:
|
|
|
|
```tsx
|
|
export default function MyCustomLogoutButton() {
|
|
return <button onClick={() => alert('Logging out!')}>Log Out</button>
|
|
}
|
|
```
|