Payload CMS Admin Theme: 5 Steps to Restyle It for Free

Looking for a free Payload CMS admin theme you can install and forget? I went looking for one and found none. Payload has no theme marketplace and no drop-in admin skin. What it does have is an admin you can white-label with a stylesheet, a logo swap and a few injected components. For most projects that is a small job, and it costs nothing.

Here are the five steps I would follow, in the order that keeps future upgrades painless.

1. Know what you are theming

The Payload admin is a Next.js app that Payload builds from your config. In a v3 project it lives in the app/(payload) folder, next to a file made for exactly this job: custom.scss. The admin panel docs describe it as the place to add or override global styles, such as the color palette.

That is the whole theming surface for colors. There is no theme picker, no theme package to install and no skin gallery. My searches turned up a few community guides and a theme generator, but no maintained theme package I would trust on a client project. So the real question is not "which theme?" but "how little do I need to change?"

2. Change the color tokens in custom.scss

Payload styles the admin with CSS variables, so you can restyle most of it by changing a handful of them. The CSS customization docs list the families: base color shades, theme colors such as background and text, and the --theme-elevation-* scale that sets how bright a surface looks against the background.

Here is a small example for app/(payload)/custom.scss:

:root {
  --theme-bg: #f7f5f0;
  --theme-text: #15273b;
  --theme-elevation-50: #f1eee7;
  --theme-elevation-100: #e8e4da;
  --theme-elevation-800: #1d3249;
}

[data-theme='dark'] {
  --theme-bg: #0e1925;
  --theme-text: #f4f1ea;
  --theme-elevation-50: #15273b;
  --theme-elevation-100: #1d3249;
  --theme-elevation-800: #d8d2c4;
}

Two things to know:

• Every token you change needs a dark twin. Payload adjusts the elevation colors for dark mode on its own, and the docs warn you to think about dark mode whenever you override colors or elevations. Set both modes, then check both.
• Your CSS wins by default. Payload keeps its own styles inside @layer payload-default, so plain CSS in custom.scss already has the highest specificity. Use @layer payload only if you want your styles layered after Payload's.

If your brand only works in one mode, the admin.theme option can restrict the admin to a single theme.

Tradeoff: variables are the safe route. Payload also uses BEM class names, so you can target things like .dashboard directly, but class selectors are tied to Payload's internal markup. I would treat them as a last resort.

3. Swap the logo and icon

Branding is what editors notice first. Payload has two slots: graphics.Logo is the full logo, used on the login screen, and graphics.Icon is the small square mark used in the nav. Both are set under admin.components, as the root components docs show:

// payload.config.ts
admin: {
  components: {
    graphics: {
      Logo: '/components/payload/Logo',
      Icon: '/components/payload/Icon',
    },
  },
},

You cannot import an image straight into the config, so each slot points to a small React component that renders your image or SVG. If the new logo does not show up, regenerate the import map with payload generate:importmap. Paths are relative to your project's base directory, or to admin.importMap.baseDir if you set one.

A logo with dark text disappears on a dark background, so plan a light version too.

4. Inject small components instead of replacing big ones

When CSS is not enough, admin.components lets you inject components at fixed spots: beforeDashboard and afterDashboard on the dashboard, beforeNavLinks and afterNavLinks in the sidebar, and beforeLogin and afterLogin on the sign-in screen. A welcome note, a link to your editor handbook or a support contact all fit well here.

You can also replace the whole Nav or entire views. That gives full control, but you now own that UI. The custom components docs also note that components are React Server Components by default, and they recommend pinning all Payload packages to the exact same version to avoid dependency mismatches.

Tradeoff: injecting a component is low maintenance, because Payload still renders everything around it. Replacing the nav or a view means you carry every future change to that screen yourself. I would replace only when the editor workflow truly needs a different layout.

5. Use Tailwind carefully, or skip it

If your front end already runs Tailwind, you may want it in the admin too. A community guide on the Payload site covers Tailwind CSS 4 in the admin. Its main point is that Tailwind's default reset, called preflight, can override Payload's own styles. So the guide imports the theme and utilities layers and leaves preflight out. It also adds a custom dark variant that follows Payload's data-theme attribute, so Tailwind's dark classes match the admin toggle.

The guide dates from February 2025, so test it against your Payload version. It also mentions a theme generator that, by the author's own note, does not match the latest Payload release. Treat that tool as inspiration, not a drop-in fix.

Tradeoff: Tailwind in the admin lets you reuse your front-end tokens, but it adds a second styling system and a reset conflict to manage. If you only need colors and a logo, custom.scss alone is simpler.

Which Payload CMS admin theme route should you pick?

• Colors and logo only: steps 2 and 3. Lowest upkeep, and it survives upgrades best.
• Plus helper content for editors: add the injected components from step 4.
• A design system shared with your front end: consider Tailwind from step 5, and read the upgrade notes each time you update.

Design tokens work the same way here as in a theme build. In my Figma to WordPress workflow, every brand color becomes a CSS variable in one file, and a Payload admin follows the same idea.

Need a branded content admin for your team? I turn designs into clean front-end pages, build custom CMS and dashboard systems and have shipped a headless website with Next.js. Tell me about your project and I will reply with next steps.