How to theme the Payload admin panel with Tailwind CSS 4

What this guide will cover:

• How to set up Tailwind CSS 4 in a Payload project?
• Theming the Payload admin panel with your styles & colors
• Adding custom logos and icons
• Supporting Payload's dark mode
• Fine-tuning components such as cards, buttons, and navigation

1. Set up a new Payload project

Choose:

• Template: blank
• Database: MongoDB (can be local)

Once setup is complete, launch VS Code by running:

And run pnpm dev to launch your dev server. Visit http://localhost:3000/admin and create your first user.

2. Install and configure Tailwind CSS 4

To install Tailwind, you will need to follow Tailwind installation instructions with Next.js, which are outlined below.

First, install the Tailwind peer dependencies. Go back into VS Code, and run:

The next thing is to create a postcss config file at the root: postcss.config.mjs

In this file, you'll paste the config from the Tailwind installation guide.

3. Split styles: global vs. Payload

Tailwind CSS 4 introduced a simpler setup with a single import line like @tailwind base; @tailwind components; @tailwind utilities;. This works great for your frontend — but it does not play nicely with Payload’s admin panel out of the box.

Why?

Payload uses its own internal CSS system to style the admin panel.

Tailwind’s default @tailwind base layer includes preflight styles, which reset browser styles globally — and these can unintentionally override Payload’s core styling.

So instead of importing Tailwind once for your entire project, we split styles into two separate files:

• One for the frontend (e.g. your website)
• One for the admin panel (Payload UI)

This lets you customize each environment without breaking the other.

Step-by-step

Create a src/styles folder and two files inside:

• payloadStyles.css – for the Payload admin panel
• global.css – for your frontend (optional)

payloadStyles.css (for admin panel):

The above is a more advanced way to import TailwindCSS. It gives us the option to comment out the base layer and preflight to make it work with Payload. So it pretty much replaces the one-liner (@import "tailwindcss";), which we can then copy and use in globals.css for the frontend.

global.css (for frontend):

Then import it inside src/app/payload/layout.tsx:

This is everything we need to do to set up Tailwind 4 with a Payload project.

4. Enable Tailwind Dark Mode with Payload

Payload uses a data-theme="dark" attribute rather than relying on browser settings.

Add this to your payloadStyles.css:

Now Tailwind will respect the admin panel’s enforced light/dark mode.

5. Add custom logo and icon components

One of the great parts about Payload is the ability to white label the admin UI, essentially allowing you to brand the entire editing experience. So with Tailwind properly set, we'll now work on customizing the logo and icon components.

Note: You can see the dark and light mode icons & logos I've created here, but since they're not prepackaged for this guide, simply create your own to follow along.

You can’t import images directly into Payload’s admin config. Instead, you’ll need to create a custom React component that renders your logo or icon, and then reference that component in the Payload config to replace the default branding.

In order to do this, we're going to create a new folder structure: src/components/payload/

Inside, create logo.tsx and icon.tsx.

Logo.tsx:

Icon.tsx:

Next, update your payload.config.ts:

Now, return to your admin panel to see if you can see your custom logo and icons.

If the assets do not appear right away, run:

6. Customize colors, borders, and layout

All elements in the Payload admin UI have several utility classes. You can override them via CSS in payloadStyles.css.

For inspiration, we have a Payload UI theme generator, with a quick caveat: as of this guide, the theme generator doesn't reflect the latest version of Payload. So it will not work entirely. However, you can take a look at the generated CSS code and pick a few out that might be relevant for you, such as the hamburger wrapper or the theme accent color among others.

To style this, simply go back into payloadStyles.css and paste in whatever styles you'd like to apply. In the example below, we're changing theme elevation colors—in this case, just three variants of it. We'll also apply a background color to the cards in our dashboard.

Example:

As you return to your admin panel, you should see your updates! Of course, you will want to make any additional adjustments to match your own brand, but I hope that has given you an idea of how to white label your Payload admin panel.