---
title: Swap in your own React components
label: Custom Components
order: 40
desc: Fully customize your Admin Panel by swapping in your own React components. Add fields, remove views, update routes and change functions to sculpt your perfect Dashboard.
keywords: admin, components, custom, documentation, Content Management System, cms, headless, javascript, node, react, nextjs
---

The Payload [Admin Panel](./overview) is designed to be as minimal and straightforward as possible to allow for both easy customization and full control over the UI. In order for Payload to support this level of customization, Payload provides a pattern for you to supply your own React components through your [Payload Config](../configuration/overview).

All Custom Components in Payload are [React Server Components](https://react.dev/reference/rsc/server-components) by default, with the exception of [Custom Providers](#custom-providers). This enables the use of the [Local API](../local-api) directly on the front-end. Custom Components are available for nearly every part of the Admin Panel for extreme granularity and control.

<Banner type="success">
  <strong>Note:</strong>
  Client Components continue to be fully supported. To use Client Components in your app, simply include the `use client` directive. Payload will automatically detect and remove all default, [non-serializable props](https://react.dev/reference/rsc/use-client#serializable-types) before rendering your component. [More details](#client-components).
</Banner>

There are four main types of Custom Components in Payload:

- [Root Components](#root-components)
- [Collection Components](./collections#components)
- [Global Components](./globals#components)
- [Field Components](./fields)

To swap in your own Custom Component, consult the list of available components. Determine the scope that corresponds to what you are trying to accomplish, then [author your React component(s)](#building-custom-components) accordingly.


## Defining Custom Components in the Payload Config

In the Payload Config, you can define custom React Components to enhance the admin interface. However, these components should not be imported directly into the server-only Payload Config to avoid including client-side code. Instead, you specify the path to the component. Here’s how you can do it:


src/components/Logout.tsx
```tsx
'use client'
import React from 'react'

export const MyComponent = () => {
  return (
    <button>Click me!</button>
  )
}
```

payload.config.ts:
```ts
import { buildConfig } from 'payload'

const config = buildConfig({
  // ...
  admin: { // highlight-line
    components: {
      logout: {
        Button: '/src/components/Logout#MyComponent'
      }
    }
  },
})
```

In the path `/src/components/Logout#MyComponent`, `/src/components/Logout` is the file path, and `MyComponent` is the named export. If the component is the default export, the export name can be omitted. Path and export name are separated by a `#`.

### Configuring the Base Directory

Component paths, by default, are relative to your working directory - this is usually where your Next.js config lies. To simplify component paths, you have the option to configure the *base directory* using the `admin.baseDir.baseDir` property:

```ts
import { buildConfig } from 'payload'
import { fileURLToPath } from 'node:url'
import path from 'path'
const filename = fileURLToPath(import.meta.url)
const dirname = path.dirname(filename)

const config = buildConfig({
  // ...
  admin: { // highlight-line
     importMap: {
      baseDir: path.resolve(dirname, 'src'),
    },
    components: {
      logout: {
        Button: '/components/Logout#MyComponent'
      }
    }
  },
})
```

In this example, we set the base directory to the `src` directory - thus we can omit the `/src/` part of our component path string.

### Passing Props

Each React Component in the Payload Config is typed as `PayloadComponent`. This usually is a string, but can also be an object containing the following properties:

| Property      | Description                                                                                                                   |
|---------------|-------------------------------------------------------------------------------------------------------------------------------|
| `clientProps` | Props to be passed to the React Component if it's a Client Component                                                          |
| `exportName`  | Instead of declaring named exports using `#` in the component path, you can also omit them from `path` and pass them in here. |
| `path`        | Path to the React Component. Named exports can be appended to the end of the path, separated by a `#`                         |
| `serverProps` | Props to be passed to the React Component if it's a Server Component                                                          |

To pass in props from the config, you can use the `clientProps` and/or `serverProps` properties. This alleviates the need to use an HOC (Higher-Order-Component) to declare a React Component with props passed in.

Here is an example:

src/components/Logout.tsx
```tsx
'use client'
import React from 'react'

export const MyComponent = ({ text }: { text: string }) => {
  return (
    <button>Click me! {text}</button>
  )
}
```

payload.config.ts:
```ts
import { buildConfig } from 'payload'

const config = buildConfig({
  // ...
  admin: { // highlight-line
    components: {
      logout: {
        Button: {
          path: '/src/components/Logout',
          clientProps: {
            text: 'Some Text.'
          },
          exportName: 'MyComponent'
        }
      }
    }
  },
})
```

### Import Maps

It's essential to understand how `PayloadComponent` paths function behind the scenes. Directly importing React Components into your Payload Config using import statements can introduce client-only modules like CSS into your server-only config. This could error when attempting to load the Payload Config in server-only environments and unnecessarily increase the size of the Payload Config, which should remain streamlined and efficient for server use.

Instead, we utilize component paths to reference React Components. This method enhances the Payload Config with actual React Component imports on the client side, without affecting server-side usage. A script is deployed to scan the Payload Config, collecting all component paths and creating an `importMap.js`. This file, located in app/(payload)/admin/importMap.js, must be statically imported by your Next.js root page and layout. The script imports all the React Components from the specified paths into a Map, associating them with their respective paths (the ones you defined).

When constructing the `ClientConfig`, Payload uses the component paths as keys to fetch the corresponding React Component imports from the Import Map. It then substitutes the `PayloadComponent` with a `MappedComponent`. A `MappedComponent` includes the React Component and additional metadata, such as whether it's a server or a client component and which props it should receive. These components are then rendered through the `<RenderComponent />` component within the Payload Admin Panel.

Import maps are regenerated whenever you modify any element related to component paths. This regeneration occurs at startup and whenever Hot Module Replacement (HMR) runs. If the import maps fail to regenerate during HMR, you can restart your application and execute the `payload generate:importmap` command to manually create a new import map. If you encounter any errors running this command, see the [Troubleshooting](/docs/beta/local-api/outside-nextjs#troubleshooting) section.

### Component paths in external packages

Component paths are resolved relative to your project's base directory, which is either your current working directory or the directory specified in `config.admin.baseDir`. When using custom components from external packages, you can't use relative paths. Instead, use an import path that's accessible as if you were writing an import statement in your project's base directory.

For example, to export a field with a custom component from an external package named `my-external-package`:

```ts
import type { Field } from 'payload'
export const MyCustomField: Field = {
  type: 'text',
  name: 'MyField',
  admin: {
    components: {
      Field: 'my-external-package/client#MyFieldComponent'
    }
  }
}
```

Despite `MyFieldComponent` living in `src/components/MyFieldComponent.tsx` in `my-external-package`, this will not be accessible from the consuming project. Instead, we recommend exporting all custom components from one file in the external package. For example, you can define a `src/client.ts file in `my-external-package`:

```ts
'use client'
export { MyFieldComponent } from './components/MyFieldComponent'
```

Then, update the package.json of `my-external-package:

```json
{
...
  "exports": {
    "./client": {
        "import": "./dist/client.js",
        "types": "./dist/client.d.ts",
        "default": "./dist/client.js"
    }
  }
}
```

This setup allows you to specify the component path as `my-external-package/client#MyFieldComponent` as seen above. The import map will generate:

```ts
import { MyFieldComponent } from 'my-external-package/client'
```

which is a valid way to access MyFieldComponent that can be resolved by the consuming project.

### Custom Components from unknown locations

By default, any component paths from known locations are added to the import map. However, if you need to add any components from unknown locations to the import map, you can do so by adding them to the `admin.dependencies` array in your Payload Config. This is mostly only relevant for plugin authors and not for regular Payload users.

Example:

```ts
export default {
  // ...
  admin: {
    // ...
    dependencies: {
      myTestComponent: { // myTestComponent is the key - can be anything
        path: '/components/TestComponent.js#TestComponent',
        type: 'component',
        clientProps: {
          test: 'hello',
        },
      },
    },
  }
}
```

This way, `TestComponent` is added to the import map, no matter if it's referenced in a known location or not. On the client, you can then use the component like this:

```tsx
'use client'

import { RenderComponent, useConfig } from '@payloadcms/ui'
import React from 'react'

export const CustomView = () => {
  const { config } = useConfig()
  return (
    <div>
      <RenderComponent mappedComponent={config.admin.dependencies?.myTestComponent} />
    </div>
  )
}
```

## Root Components

Root Components are those that effect the [Admin Panel](./overview) generally, such as the logo or the main nav.

To override Root Components, use the `admin.components` property in your [Payload Config](../getting-started/overview):

```ts
import { buildConfig } from 'payload'

export default buildConfig({
  // ...
  admin: {
    // highlight-start
    components: {
      // ...
    },
    // highlight-end
  },
})
```

_For details on how to build Custom Components, see [Building Custom Components](#building-custom-components)._

The following options are available:

| Path                  | Description                                                                                                                                                                                                         |
|-----------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **`Nav`**             | Contains the sidebar / mobile menu in its entirety.                                                                                                                                                                 |
| **`beforeNavLinks`**  | An array of Custom Components to inject into the built-in Nav, _before_ the links themselves.                                                                                                                       |
| **`afterNavLinks`**   | An array of Custom Components to inject into the built-in Nav, _after_ the links.                                                                                                                                   |
| **`beforeDashboard`** | An array of Custom Components to inject into the built-in Dashboard, _before_ the default dashboard contents.                                                                                                       |
| **`afterDashboard`**  | An array of Custom Components to inject into the built-in Dashboard, _after_ the default dashboard contents.                                                                                                        |
| **`beforeLogin`**     | An array of Custom Components to inject into the built-in Login, _before_ the default login form.                                                                                                                   |
| **`afterLogin`**      | An array of Custom Components to inject into the built-in Login, _after_ the default login form.                                                                                                                    |
| **`logout.Button`**   | The button displayed in the sidebar that logs the user out.                                                                                                                                                         |
| **`graphics.Icon`**   | The simplified logo used in contexts like the the `Nav` component.                                                                                                                                                  |
| **`graphics.Logo`**   | The full logo used in contexts like the `Login` view.                                                                                                                                                               |
| **`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).                                       |
| **`actions`**         | An array of Custom Components to be rendered in the header of the Admin Panel, providing additional interactivity and functionality.                                                                  |
| **`views`**           | Override or create new views within the Admin Panel. [More details](./views).                                                                                                                                 |

<Banner type="success">
  <strong>Note:</strong>
  You can also use set [Collection Components](./collections#components) and [Global Components](./globals#components) in their respective configs.
</Banner>

### Custom Providers

As you add more and more Custom Components to your [Admin Panel](./overview), you may find it helpful to add additional [React Context](https://react.dev/learn/scaling-up-with-reducer-and-context)(s). Payload allows you to inject your own context providers in your app so you can export your own custom hooks, etc.

To add a Custom Provider, use the `admin.components.providers` property in your [Payload Config](../getting-started/overview):

```ts
import { buildConfig } from 'payload'

export default buildConfig({
  // ...
  admin: {
    components: {
      providers: ['/path/to/MyProvider'], // highlight-line
    },
  },
})
```

Then build your Custom Provider as follows:

```tsx
'use client'
import React, { createContext, useContext } from 'react'

const MyCustomContext = React.createContext(myCustomValue)

export const MyProvider: React.FC = ({ children }) => {
  return (
    <MyCustomContext.Provider value={myCustomValue}>
      {children}
    </MyCustomContext.Provider>
  )
}

export const useMyCustomContext = () => useContext(MyCustomContext)
```

<Banner type="warning">
  <strong>Reminder:</strong> Custom Providers are by definition Client Components. This means they must include the `use client` directive at the top of their files and cannot use server-only code.
</Banner>

## Building Custom Components

All Custom Components in Payload are [React Server Components](https://react.dev/reference/rsc/server-components) by default, with the exception of [Custom Providers](#custom-providers). This enables the use of the [Local API](../local-api) directly on the front-end, among other things.

To make building Custom Components as easy as possible, Payload automatically provides common props, such as the [`payload`](../local-api/overview) class and the [`i18n`](../configuration/i18n) object. This means that when building Custom Components within the Admin Panel, you do not have to get these yourself.

Here is an example:

```tsx
import React from 'react'

const MyServerComponent = async ({
  payload // highlight-line
}) => {
  const page = await payload.findByID({
    collection: 'pages',
    id: '123',
  })

  return (
    <p>{page.title}</p>
  )
}
```

Each Custom Component receives the following props by default:

| Prop                      | Description                                                                                           |
| ------------------------- | ----------------------------------------------------------------------------------------------------- |
| `payload`                 | The [Payload](../local-api/overview) class.                                                           |
| `i18n`                    | The [i18n](../i18n) object.                                                                           |

Custom Components also receive various other props that are specific to the context in which the Custom Component is being rendered. For example, [Custom Views](./views) receive the `user` prop. For a full list of available props, consult the documentation related to the specific component you are working with.

<Banner type="success">
  See [Root Components](#root-components), [Collection Components](#collection-components), [Global Components](#global-components), or [Field Components](#custom-field-components) for a complete list of all available components.
</Banner>

### Client Components

When [Building Custom Components](#building-custom-components), it's still possible to use client-side code such as `useState` or the `window` object. To do this, simply add the `use client` directive at the top of your file. Payload will automatically detect and remove all default, [non-serializable props](https://react.dev/reference/rsc/use-client#serializable-types) before rendering your component.

```tsx
'use client' // highlight-line
import React, { useState } from 'react'

export const MyClientComponent: React.FC = () => {
  const [count, setCount] = useState(0)

  return (
    <button onClick={() => setCount(count + 1)}>
      Clicked {count} times
    </button>
  )
}
```

<Banner type="warning">
  <strong>Reminder:</strong>
  Client Components cannot be passed [non-serializable props](https://react.dev/reference/rsc/use-client#serializable-types). If you are rendering your Client Component _from within_ a Server Component, ensure that its props are serializable.
</Banner>

### Accessing the Payload Config

From any Server Component, the [Payload Config](../configuration/overview) can be accessed directly from the `payload` prop:

```tsx
import React from 'react'

export default async function MyServerComponent({
  payload: {
    config // highlight-line
  }
}) {
  return (
    <Link href={config.serverURL}>
      Go Home
    </Link>
  )
}
```

But, the Payload Config is [non-serializable](https://react.dev/reference/rsc/use-client#serializable-types) by design. It is full of custom validation functions, React components, etc. This means that the Payload Config, in its entirety, cannot be passed directly to Client Components.

For this reason, Payload creates a Client Config and passes it into the Config Provider. This is a serializable version of the Payload Config that can be accessed from any Client Component via the [`useConfig`](./hooks#useconfig) hook:

```tsx
import React from 'react'
import { useConfig } from '@payloadcms/ui'

export const MyClientComponent: React.FC = () => {
  const { config: { serverURL } } = useConfig() // highlight-line

  return (
    <Link href={serverURL}>
      Go Home
    </Link>
  )
}
```

<Banner type="success">
  See [Using Hooks](#using-hooks) for more details.
</Banner>

All [Field Components](./fields) automatically receive their respective Client Field Config through a common [`field`](./fields#the-field-prop) prop:

```tsx
'use client'
import React from 'react'
import type { TextFieldProps } from 'payload'

export const MyClientFieldComponent: TextFieldProps = ({ field: { name } }) => {
  return (
    <p>
      {`This field's name is ${name}`}
    </p>
  )
}
```

### Using Hooks

To make it easier to [build your Custom Components](#building-custom-components), you can use [Payload's built-in React Hooks](./hooks) in any Client Component. For example, you might want to interact with one of Payload's many React Contexts:

```tsx
'use client'
import React from 'react'
import { useDocumentInfo } from '@payloadcms/ui'

export const MyClientComponent: React.FC = () => {
  const { slug } = useDocumentInfo() // highlight-line

  return (
    <p>{`Entity slug: ${slug}`}</p>
  )
}
```

<Banner type="success">
  See the [Hooks](./hooks) documentation for a full list of available hooks.
</Banner>

### Getting the Current Language

All Custom Components can support multiple languages to be consistent with Payload's [Internationalization](../configuration/i18n). To do this, first add your translation resources to the [I18n Config](../configuration/i18n).

From any Server Component, you can translate resources using the `getTranslation` function from `@payloadcms/translations`. All Server Components automatically receive the `i18n` object as a prop by default.

```tsx
import React from 'react'
import { getTranslation } from '@payloadcms/translations'

export default async function MyServerComponent({ i18n }) {
  const translatedTitle = getTranslation(myTranslation, i18n) // highlight-line

  return (
    <p>{translatedTitle}</p>
  )
}
```

The best way to do this within a Client Component is to import the `useTranslation` hook from `@payloadcms/ui`:

```tsx
import React from 'react'
import { useTranslation } from '@payloadcms/ui'

export const MyClientComponent: React.FC = () => {
  const { t, i18n } = useTranslation() // highlight-line

  return (
    <ul>
      <li>{t('namespace1:key', { variable: 'value' })}</li>
      <li>{t('namespace2:key', { variable: 'value' })}</li>
      <li>{i18n.language}</li>
    </ul>
  )
}
```

<Banner type="success">
  See the [Hooks](./hooks) documentation for a full list of available hooks.
</Banner>

### Getting the Current Locale

All [Custom Views](./views) can support multiple locales to be consistent with Payload's [Localization](../configuration/localization). They automatically receive the `locale` object as a prop by default. This can be used to scope API requests, etc.:

```tsx
import React from 'react'

export default async function MyServerComponent({ payload, locale }) {
  const localizedPage = await payload.findByID({
    collection: 'pages',
    id: '123',
    locale,
  })

  return (
    <p>{localizedPage.title}</p>
  )
}
```

The best way to do this within a Client Component is to import the `useLocale` hook from `@payloadcms/ui`:

```tsx
import React from 'react'
import { useLocale } from '@payloadcms/ui'

const Greeting: React.FC = () => {
  const locale = useLocale() // highlight-line

  const trans = {
    en: 'Hello',
    es: 'Hola',
  }

  return (
    <span>{trans[locale.code]}</span>
  )
}
```

<Banner type="success">
  See the [Hooks](./hooks) documentation for a full list of available hooks.
</Banner>

### Styling Custom Components

Payload has a robust [CSS Library](./customizing-css) that you can use to style your Custom Components similarly to Payload's built-in styling. This will ensure that your Custom Components match the existing design system, and so that they automatically adapt to any theme changes that might occur.

To apply custom styles, simply import your own `.css` or `.scss` file into your Custom Component:

```tsx
import './index.scss'

export const MyComponent: React.FC = () => {
  return (
    <div className="my-component">
      My Custom Component
    </div>
  )
}
```

Then to colorize your Custom Component's background, for example, you can use the following CSS:

```scss
.my-component {
  background-color: var(--theme-elevation-500);
}
```

Payload also exports its [SCSS](https://sass-lang.com) library for reuse which includes mixins, etc. To use this, simply import it as follows into your `.scss` file:

```scss
@import '~payload/scss';

.my-component {
  @include mid-break {
    background-color: var(--theme-elevation-900);
  }
}

```

<Banner type="success">
  <strong>Note:</strong>
  You can also drill into Payload's own component styles, or easily apply global, app-wide CSS. More on that [here](./customizing-css).
</Banner>