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:

1. Exposes a root-level stylesheet for you to easily to inject custom selectors
2. Provides a CSS library that can be easily overridden or extended
3. 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 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:

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

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.

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.