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