---
title: "Payload CMS — Admin Panel Overview"
aliases: [payload-admin, payloadcms-admin-panel]
tags: [payloadcms, admin, nextjs, react, cms, auth, i18n]
sources: [raw/admin__overview.md]
created: 2026-05-15
updated: 2026-05-15
---

## What It Is

Payload auto-generates a fully type-safe, React/Next.js Admin Panel for managing users and data. Built on the **Next.js App Router** with React Server Components. Supports 100+ fields with no performance degradation; translated into 30+ languages.

## Project Structure

All Payload routes live inside the `(payload)` route group:

```
app/
├─ (payload)/
│  ├─ admin/[[...segments]]/   ← Admin UI pages
│  ├─ api/[...slug]/           ← REST API
│  ├─ graphql/                 ← GraphQL API
│  ├─ graphql-playground/
│  ├─ custom.scss              ← Global style overrides
│  └─ layout.tsx               ← Sets html lang/dir attrs
```

- Move `(payload)` anywhere by updating `routes` + `admin.importMap` in config.
- Delete unwanted directories (admin, api, graphql) to opt out — overhead is fully scoped.

## Key Config Options (`admin` key in Payload Config)

| Option | Purpose |
|--------|---------|
| `user` | Slug of auth-enabled Collection that can log in |
| `components` | Swap in custom React components globally |
| `routes` | Override built-in admin route paths |
| `livePreview` | Real-time front-end preview |
| `theme` | Lock to `light` or `dark`, default `all` |
| `timezones` | IANA timezone list + default (display only; DB always UTC) |
| `toast` | Duration, position, limit of toast notifications |
| `dateFormat` | Any `date-fns` format string |
| `meta` | SEO metadata for the panel |
| `autoLogin` | Dev/demo convenience auto-login |

## Auth & User Collection

- Only **one** auth-enabled Collection can access the Admin Panel.
- Default: auto-generated `users` collection. Override by adding your own `slug: 'users'`.
- Set `admin: { user: 'admins' }` to use a different collection (e.g. separate `admins` vs `customers`).

### Role-Based Access Control (RBAC)

Add a `roles` field to the auth collection → use `access.admin` to gate panel entry. Multiple roles (e.g. `super-admin`, `editor`) can share the same collection with different permission levels.

## Customizing Routes

### Root-level Routes

```ts
routes: {
  admin: '/custom-admin-route',   // default: /admin
  api: '/api',
  graphQL: '/graphql',
  graphQLPlayground: '/graphql-playground',
}
```

Changing `routes.admin` requires updating the file system structure to match.

### Admin-level Routes

```ts
admin: {
  routes: {
    account: '/my-account',   // default: /account
    login: '/login',
    logout: '/logout',
    forgot: '/forgot',
    reset: '/reset',
    unauthorized: '/unauthorized',
    inactivity: '/logout-inactivity',
    createFirstUser: '/create-first-user',
  }
}
```

## I18n

- 30+ languages auto-detected from browser locale.
- Users can override from their account page.
- Falls back to English if locale unsupported.

## Timezones

- Dates **always stored in UTC** in DB; timezone config is display-only.
- `supportedTimezones`: array of `{label, value}` (IANA names) **or** a function `({ defaultTimezones }) => [...]` to extend defaults.
- `defaultTimezone`: IANA string, e.g. `America/Los_Angeles`.
- Must also enable `timezone: true` on individual Date fields.
- Use `{ label: 'UTC', value: 'UTC' }` to show raw UTC to editors.

## Toast Notifications (Sonner library)

| Option | Default | Notes |
|--------|---------|-------|
| `duration` | 4000ms | Display time per toast |
| `position` | `bottom-right` | Screen position |
| `limit` | 5 | Max visible at once |
| `expand` | false | Show all without hover |

## Gotchas

- `importMap.js` is **regenerated on every startup/HMR** — never edit directly; configure component paths in Payload config instead.
- `layout.tsx` says "DO NOT MODIFY" but is only generated once — safe to edit.
- Most other `(payload)` files are generated once and safe to modify.

## Key Takeaways

- Admin Panel = Next.js App Router app nested in `(payload)` route group; REST + GraphQL APIs are just Next.js routes alongside it.
- White-label ready: every field label, view, and style is swappable via Custom Components.
- Single auth-enabled Collection gates admin access; RBAC via `access.admin`.
- `routes` config (root-level) + `admin.routes` (panel-level) give full URL control — but root changes require FS changes too.
- Timezone config is display-only; DB always UTC; must opt in per Date field.
- `importMap.js` is the only auto-regenerated file — treat as read-only.

## Related

- [[wiki/payloadcms/custom-components|Custom Components]]
- [[wiki/tech-patterns/_index|Tech Patterns — Payload CMS]]
- [[wiki/architecture/_index|Architecture Patterns]]
- [[wiki/claude-code/_index|Claude Code — Next.js integration]]

---

*Source: `raw/admin__overview.md` — https://payloadcms.com/docs/admin/overview*