127 lines
4.2 KiB
Markdown
127 lines
4.2 KiB
Markdown
---
|
|
title: "Custom Components — Root Components"
|
|
aliases: [root-components, admin-root-components, payload-root-components]
|
|
tags: [payloadcms, admin, custom-components, react, white-label]
|
|
sources: [raw/custom-components__root-components.md]
|
|
created: 2026-05-15
|
|
updated: 2026-05-15
|
|
---
|
|
|
|
# Custom Components — Root Components
|
|
|
|
Root Components affect the Admin Panel at a high level — logo, nav, header, login view, dashboard injections. Combined with [[wiki/payloadcms/admin-panel-overview|Custom CSS]], they enable full white-labeling.
|
|
|
|
All root components are configured under `admin.components` in [[wiki/payloadcms/configuration|Payload Config]]:
|
|
|
|
```ts
|
|
import { buildConfig } from 'payload'
|
|
|
|
export default buildConfig({
|
|
admin: {
|
|
components: {
|
|
// root component slots here
|
|
},
|
|
},
|
|
})
|
|
```
|
|
|
|
## Config Slots
|
|
|
|
| Property | Type | Description |
|
|
|----------|------|-------------|
|
|
| `actions` | `Component[]` | Rendered inside the Admin Panel header — buttons, widgets |
|
|
| `header` | `Component[]` | Injected **above** the Payload header (banners, notifications) |
|
|
| `beforeDashboard` | `Component[]` | Before default dashboard content |
|
|
| `afterDashboard` | `Component[]` | After default dashboard content |
|
|
| `beforeLogin` | `Component[]` | Before login form |
|
|
| `afterLogin` | `Component[]` | After login form |
|
|
| `beforeNavLinks` | `Component[]` | Before nav links in sidebar |
|
|
| `afterNavLinks` | `Component[]` | After nav links in sidebar |
|
|
| `settingsMenu` | `Component[]` | Popup menu via gear icon above logout button |
|
|
| `Nav` | `Component` | **Replaces** the entire sidebar/mobile menu |
|
|
| `graphics.Icon` | `Component` | Small square icon in Nav context |
|
|
| `graphics.Logo` | `Component` | Full logo in Login view context |
|
|
| `logout.Button` | `Component` | Replaces the logout button |
|
|
| `providers` | `Component[]` | React Context providers wrapping entire Admin Panel |
|
|
| `views` | `object` | Override or add views — see [[wiki/payloadcms/custom-views|Custom Views]] |
|
|
|
|
## Component Examples
|
|
|
|
### Inject slots (arrays)
|
|
|
|
```ts
|
|
admin: {
|
|
components: {
|
|
actions: ['/path/to/MyAction'],
|
|
beforeDashboard: ['/path/to/MyWidget'],
|
|
afterNavLinks: ['/path/to/MyNavItem'],
|
|
},
|
|
}
|
|
```
|
|
|
|
### settingsMenu — use `PopupList` from `@payloadcms/ui`
|
|
|
|
```tsx
|
|
'use client'
|
|
import { PopupList } from '@payloadcms/ui'
|
|
|
|
export function MySettingsMenu() {
|
|
return (
|
|
<PopupList.ButtonGroup>
|
|
<PopupList.Button onClick={() => console.log('triggered')}>
|
|
Custom Action
|
|
</PopupList.Button>
|
|
</PopupList.ButtonGroup>
|
|
)
|
|
}
|
|
```
|
|
|
|
Multiple named exports → pass `#ComponentName` in path:
|
|
```ts
|
|
settingsMenu: ['/components/SystemActions#SystemActions']
|
|
```
|
|
|
|
### Replace entire Nav
|
|
|
|
```tsx
|
|
import { Link } from '@payloadcms/ui'
|
|
|
|
export default function MyCustomNav() {
|
|
return (
|
|
<nav>
|
|
<ul>
|
|
<li><Link href="/dashboard">Dashboard</Link></li>
|
|
</ul>
|
|
</nav>
|
|
)
|
|
}
|
|
```
|
|
|
|
### Custom Logo / Icon
|
|
|
|
```ts
|
|
admin: {
|
|
components: {
|
|
graphics: {
|
|
Icon: '/path/to/MyIcon', // small, in Nav
|
|
Logo: '/path/to/MyLogo', // full, in Login view
|
|
},
|
|
},
|
|
}
|
|
```
|
|
|
|
## Key Takeaways
|
|
|
|
- Root components configure under `admin.components` — this is different from collection/global component slots
|
|
- **Injection slots** (`before*`, `after*`, `actions`, `header`, `settingsMenu`) accept arrays — multiple components stack
|
|
- **Replacement slots** (`Nav`, `graphics.Icon`, `graphics.Logo`, `logout.Button`) accept a single component path and fully replace the built-in
|
|
- `providers` wraps the entire Admin Panel — use for React Context shared across all views
|
|
- `settingsMenu` requires `PopupList` from `@payloadcms/ui` for consistent styling
|
|
- Use `graphics.Icon` + `graphics.Logo` + Custom CSS for brand white-labeling with minimal code
|
|
- Actions can also be added per-view in [[wiki/payloadcms/custom-components-edit-view|Edit View]] and [[wiki/payloadcms/custom-components-list-view|List View]] configs
|
|
- For component authoring conventions (path syntax, RSC vs Client) see [[wiki/payloadcms/custom-components-authoring|Custom Components Authoring Guide]]
|
|
|
|
## Sources
|
|
|
|
- `raw/custom-components__root-components.md`
|
|
- https://payloadcms.com/docs/custom-components/root-components
|