92 lines
3.1 KiB
Markdown
92 lines
3.1 KiB
Markdown
---
|
|
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
|