9f9db3ff81
## Introducing Prettier for docs
Prettier [was originally disabled for our docs as it didn't support MDX
2.0](1fa636417f),
outputting invalid MDX syntax.
This has since been fixed - prettier now supports MDX 2.0.
## Reducing print width
This also reduces the print width for the docs folder from 100 to 70.
Our docs code field are very narrow - this should help make code more
readable.
**Before**
**After**
**Before**
**After**
90 lines
4.5 KiB
Plaintext
90 lines
4.5 KiB
Plaintext
---
|
|
title: Customizing CSS & SCSS
|
|
label: Customizing CSS
|
|
order: 50
|
|
desc: Customize the Payload Admin Panel further by adding your own CSS or SCSS style sheet to the configuration, powerful theme and design options are waiting for you.
|
|
keywords: admin, css, scss, documentation, Content Management System, cms, headless, javascript, node, react, nextjs
|
|
---
|
|
|
|
Customizing the Payload [Admin Panel](./overview) 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](#global-css) for you to inject custom selectors
|
|
1. Provides a [CSS library](#css-library) that can be easily overridden or extended
|
|
1. Uses [BEM naming conventions](http://getbem.com) 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](./overview). 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:
|
|
|
|
```scss
|
|
.dashboard {
|
|
background-color: red; // highlight-line
|
|
}
|
|
```
|
|
|
|
<Banner type="warning">
|
|
**Note:** If you are building [Custom
|
|
Components](../custom-components/overview), it is best to import your own
|
|
stylesheets directly into your components, rather than using the global
|
|
stylesheet. You can continue to use the [CSS library](#css-library) as needed.
|
|
</Banner>
|
|
|
|
### 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
|
|
|
|
```css
|
|
@layer payload-default {
|
|
// my styles within the payload specificity
|
|
}
|
|
```
|
|
|
|
## 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.
|
|
|
|
```scss
|
|
@import '~@payloadcms/ui/scss';
|
|
```
|
|
|
|
## CSS Library
|
|
|
|
To make it as easy as possible for you to override default styles, Payload uses [BEM naming conventions](http://getbem.com/) 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](https://developer.mozilla.org/en-US/docs/Web/CSS/Using_CSS_custom_properties). 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](https://github.com/payloadcms/payload/blob/main/packages/ui/src/scss/queries.scss)
|
|
- [Colors](https://github.com/payloadcms/payload/blob/main/packages/ui/src/scss/colors.scss)
|
|
- 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](https://github.com/payloadcms/payload/blob/main/packages/ui/src/scss/app.scss)
|
|
- Horizontal gutter
|
|
- Transition speeds
|
|
- Font sizes
|
|
- Etc.
|
|
|
|
For an up-to-date, comprehensive list of all available variables, please refer to the [Source Code](https://github.com/payloadcms/payload/blob/main/packages/ui/src/scss).
|
|
|
|
<Banner type="warning">
|
|
**Warning:** If you're overriding colors or theme elevations, make sure to
|
|
consider how [your changes will affect dark mode](#dark-mode).
|
|
</Banner>
|
|
|
|
#### Dark Mode
|
|
|
|
Colors are designed to automatically adapt to theme of the [Admin Panel](./overview). 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.
|