Root Components - Payload

Root Components are those that affect the Admin Panel at a high-level, such as the logo or the main nav. You can swap out these components with your own Custom Components to create a completely custom look and feel.

When combined with Custom 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:

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.
`afterDashboard`	An array of Custom Components to inject into the built-in Dashboard, after the default dashboard contents. More details.
`afterLogin`	An array of Custom Components to inject into the built-in Login, after the default login form. More details.
`afterNavLinks`	An array of Custom Components to inject into the built-in Nav, after the links. More details.
`beforeDashboard`	An array of Custom Components to inject into the built-in Dashboard, before the default dashboard contents. More details.
`beforeLogin`	An array of Custom Components to inject into the built-in Login, before the default login form. More details.
`beforeNavLinks`	An array of Custom Components to inject into the built-in Nav, before the links themselves. More details.
`graphics.Icon`	The simplified logo used in contexts like the `Nav` component. More details.
`graphics.Logo`	The full logo used in contexts like the `Login` view. More details.
`header`	An array of Custom Components to be injected above the Payload header. More details.
`logout.Button`	The button displayed in the sidebar that logs the user out. More details.
`Nav`	Contains the sidebar / mobile menu in its entirety. More details.
`settingsMenu`	An array of Custom Components to inject into a popup menu accessible via a gear icon above the logout button. More details.
`providers`	Custom React Context providers that will wrap the entire Admin Panel. More details.
`views`	Override or create new views within the Admin Panel. More details.

For details on how to build Custom Components, see Building Custom Components.

<Banner type="success"> **Note:** You can also 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:

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:

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

<Banner type="success"> **Note:** You can also set [Dashboard Widgets](../custom-components/dashboard) in the `admin.dashboard` property, or replace the entire [Dashboard View](../custom-components/dashboard) with your own. </Banner>

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:

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:

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:

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, before the nav links themselves.

To add beforeNavLinks components, use the admin.components.beforeNavLinks property in your Payload Config:

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:

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

settingsMenu

The settingsMenu property allows you to inject Custom Components into a popup menu accessible via a gear icon in the navigation controls, positioned above the logout button. This is ideal for adding custom actions, utilities, or settings that are relevant at the admin level.

To add settingsMenu components, use the admin.components.settingsMenu property in your Payload Config:

import { buildConfig } from 'payload'

export default buildConfig({
  // ...
  admin: {
    // highlight-start
    components: {
      settingsMenu: ['/path/to/your/component#ComponentName'],
    },
    // highlight-end
  },
})

Here is an example of a simple settingsMenu component:

tsx

'use client'
import { PopupList } from '@payloadcms/ui'

export function MySettingsMenu() {
  return (
    <PopupList.ButtonGroup>
      <PopupList.Button onClick={() => console.log('Action triggered')}>
        Custom Action
      </PopupList.Button>
      <PopupList.Button onClick={() => window.open('/admin/custom-page')}>
        Custom Page
      </PopupList.Button>
    </PopupList.ButtonGroup>
  )
}

You can pass multiple components to create organized groups of menu items:

import { buildConfig } from 'payload'

export default buildConfig({
  // ...
  admin: {
    components: {
      settingsMenu: [
        '/components/SystemActions#SystemActions',
        '/components/DataManagement#DataManagement',
      ],
    },
  },
})

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:

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:

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 
}

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:

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 
}

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:

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:

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