Customizing CSS & SCSS

Customizing the Payload Admin Panel through CSS alone is one of the easiest and most powerful ways to customize the look and feel of the dashboard. To allow for this level of customization, Payload:

Exposes a root-level stylesheet for you to easily to inject custom selectors
Provides a CSS library that can be easily overridden or extended
Uses BEM naming conventions so that class names are globally accessible

To customize the CSS within the Admin UI, determine scope and change you'd like to make, and then add your own CSS or SCSS to the configuration as needed.

Global CSS

Global CSS refers to the CSS that is applied to the entire Admin Panel. This is where you can have a significant impact to the look and feel of the Admin UI through just a few lines of code.

You can add your own global CSS through the root custom.scss file of your app. This file is loaded into the root of the Admin Panel and can be used to inject custom selectors or styles however needed.

Here is an example of how you might target the Dashboard View and change the background color:

1.dashboard {
2  background-color: red; 
3}

Specificity rules

All Payload CSS is encapsulated inside CSS layers under @layer payload-default. Any custom css will now have the highest possible specificity.

We have also provided a layer @layer payload if you want to use layers and ensure that your styles are applied after payload.

To override existing styles in a way that the previous rules of specificity would be respected you can use the default layer like so

1@layer payload-default {
2  // my styles within the payload specificity
3}

Re-using Payload SCSS variables and utilities

You can re-use Payload's SCSS variables and utilities in your own stylesheets by importing it from the UI package.

1@import '~@payloadcms/ui/scss';

CSS Library

To make it as easy as possible for you to override default styles, Payload uses BEM naming conventions for all CSS within the Admin UI. If you provide your own CSS, you can override any built-in styles easily, including targeting nested components and their various component states.

You can also override Payload's built-in CSS Variables. These variables are widely consumed by the Admin Panel, so modifying them has a significant impact on the look and feel of the Admin UI.

The following variables are defined and can be overridden:

Breakpoints
Colors
- Base color shades (white to black by default)
- Success / warning / error color shades
- Theme-specific colors (background, input background, text color, etc.)
- Elevation colors (used to determine how "bright" something should be when compared to the background)
Sizing
- Horizontal gutter
- Transition speeds
- Font sizes
- Etc.

For an up-to-date, comprehensive list of all available variables, please refer to the Source Code.

Dark Mode

Colors are designed to automatically adapt to theme of the Admin Panel. By default, Payload automatically overrides all --theme-elevation colors and inverts all success / warning / error shades to suit dark mode. We also update some base theme variables like --theme-bg, --theme-text, etc.

See what others are building with Payload.

"Payload has transformed the way our clients manage content. It's an indispensable tool for any modern agency."

Deploy your entire stack in one place with Payload Cloud.

Microsoft chose Payload to tell the world about AI.