obsidian/wiki/payloadcms/admin-panel-overview.md

title	aliases	tags	sources	created	updated
Payload CMS — Admin Panel Overview	payload-admin payloadcms-admin-panel	payloadcms admin nextjs react cms auth i18n	raw/admin__overview.md	2026-05-15	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

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

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
• wiki/tech-patterns/_index
• wiki/architecture/_index
• wiki/claude-code/_index

---

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