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, they enable full white-labeling.

All root components are configured under admin.components in wiki/payloadcms/configuration:

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

Component Examples

Inject slots (arrays)

admin: {
  components: {
    actions: ['/path/to/MyAction'],
    beforeDashboard: ['/path/to/MyWidget'],
    afterNavLinks: ['/path/to/MyNavItem'],
  },
}

settingsMenu — use `PopupList` from `@payloadcms/ui`

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

settingsMenu: ['/components/SystemActions#SystemActions']

Replace entire Nav

import { Link } from '@payloadcms/ui'

export default function MyCustomNav() {
  return (
    <nav>
      <ul>
        <li><Link href="/dashboard">Dashboard</Link></li>
      </ul>
    </nav>
  )
}

Custom Logo / Icon

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 and wiki/payloadcms/custom-components-list-view configs
For component authoring conventions (path syntax, RSC vs Client) see wiki/payloadcms/custom-components-authoring

Sources

raw/custom-components__root-components.md
https://payloadcms.com/docs/custom-components/root-components

4.2 KiB Raw Permalink Blame History