---
title: "Payload CMS — Customizing CSS & SCSS"
aliases: [payload-css, payload-scss, payload-admin-css]
tags: [payload-cms, css, scss, admin-panel, theming]
sources: [raw/admin__customizing-css.md]
created: 2026-05-15
updated: 2026-05-15
---

# Payload CMS — Customizing CSS & SCSS

Three mechanisms to restyle the Admin Panel: global stylesheet, CSS variable overrides, and BEM class targeting.

## Global CSS

Add a `custom.scss` file at the root of your app — it is loaded into the Admin Panel root:

```scss
.dashboard {
  background-color: red;
}
```

> For [[wiki/tech-patterns/payload-cms-admin-panel-location|custom components]], import styles directly into the component instead of using the global stylesheet.

## CSS Specificity & Layers

All Payload styles are inside `@layer payload-default`. Custom CSS gets **highest specificity by default**.

Two layers available:

| Layer | Purpose |
|-------|---------|
| *(no layer)* | Overrides everything — use for most customizations |
| `@layer payload` | Custom styles that respect cascade order after Payload |
| `@layer payload-default` | Write within Payload's own specificity (for surgical overrides) |

```css
@layer payload-default {
  /* matches Payload's own specificity level */
}
```

## Re-using Payload SCSS Variables

Import the UI package's SCSS utilities into your own stylesheet:

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

## CSS Variable Library (BEM + Custom Properties)

Payload uses [BEM naming](http://getbem.com/) — class names are globally accessible and predictable.

Override CSS custom properties defined in `@payloadcms/ui/src/scss`:

| Variable Group | File | Controls |
|---------------|------|----------|
| Breakpoints | `queries.scss` | Responsive breakpoints |
| Colors | `colors.scss` | Base shades, success/warning/error, theme-specific bg/text/input |
| Elevation | `colors.scss` | How "bright" elements appear vs background |
| Sizing | `app.scss` | Gutters, transition speeds, font sizes |

## Dark Mode

Color variables automatically adapt to dark/light theme. Payload inverts:
- All `--theme-elevation-*` colors
- Success / warning / error shades
- Base theme vars: `--theme-bg`, `--theme-text`, etc.

**When overriding colors** — always verify both dark and light themes.

## Key Takeaways

- Global CSS → `custom.scss` at app root; highest specificity wins by default
- Use `@layer payload-default` to stay within Payload's specificity layer
- Import `~@payloadcms/ui/scss` to re-use Payload's SCSS variables
- BEM class names are stable and globally targetable
- CSS custom properties (colors, sizing, elevation) are the fastest way to retheme
- Always check dark mode when touching color variables

## Related

- [[wiki/tech-patterns/payload-cms-installation|Payload CMS — Installation & Setup]]
- [[wiki/tech-patterns/payload-cms-admin-panel-location|Payload CMS — Custom Admin Panel Location]]
- [[wiki/tech-patterns/payload-cms-admin-accessibility|Payload CMS — Admin Panel Accessibility]]
- [[wiki/tech-patterns/payload-cms-access-control-overview|Payload CMS — Access Control Overview]]

## Sources

- `raw/admin__customizing-css.md` — official Payload docs on CSS customization