005cf56baf
Some checks failed
No response / noResponse (push) Has been cancelled
CI / Continuous releases (push) Has been cancelled
CI / test-dev (macos-latest) (push) Has been cancelled
CI / test-dev (ubuntu-latest) (push) Has been cancelled
CI / test-dev (windows-latest) (push) Has been cancelled
Maintenance / main (push) Has been cancelled
Scorecards supply-chain security / Scorecards analysis (push) Has been cancelled
CodeQL / Analyze (push) Has been cancelled
45 lines
3.1 KiB
Markdown
45 lines
3.1 KiB
Markdown
# CSS theme variables
|
||
|
||
<p class="description">An overview of adopting CSS theme variables in Material UI.</p>
|
||
|
||
[CSS variables](https://www.w3.org/TR/css-variables-1/) are a modern cross-browser feature that let you declare variables in CSS and reuse them in other properties.
|
||
You can implement them to improve Material UI's theming and customization experience.
|
||
|
||
:::info
|
||
If this is your first time encountering CSS variables, you should check out [the MDN Web Docs on CSS custom properties](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_cascading_variables/Using_CSS_custom_properties) before continuing here.
|
||
:::
|
||
|
||
## Introduction
|
||
|
||
CSS theme variables replace raw values in Material UI components for a better developer experience because, in the browser dev tool, you will see which theme token is used as a value.
|
||
|
||
In addition with these variables, you can inject a theme into your app's stylesheet _at build time_ to apply the user's selected settings before the whole app is rendered.
|
||
|
||
## Advantages
|
||
|
||
- It lets you prevent [dark-mode SSR flickering](https://github.com/mui/material-ui/issues/27651).
|
||
- You can create unlimited color schemes beyond `light` and `dark`.
|
||
- It offers a better debugging experience not only for developers but also designers on your team.
|
||
- The color scheme of your website is automatically synced between browser tabs.
|
||
- It simplifies integration with third-party tools because CSS theme variables are available globally.
|
||
- It reduces the need for a nested theme when you want to apply dark styles to a specific part of your application.
|
||
|
||
## Trade-offs
|
||
|
||
For server-side applications, there are some trade-offs to consider:
|
||
|
||
| | Compare to the default method | Reason |
|
||
| :----------------------------------------------------------- | :---------------------------- | :------------------------------------------------------------------------------------------------------------- |
|
||
| HTML size | Bigger | CSS variables are generated for both light and dark mode at build time. |
|
||
| [First Contentful Paint (FCP)](https://web.dev/articles/fcp) | Longer | Since the HTML size is bigger, the time to download the HTML before showing the content is a bit longer. |
|
||
| [Time to Interactive (TTI)](https://web.dev/articles/tti) | Shorter (for dark mode) | Stylesheets are not regenerated between light and dark mode, a lot less time is spent running JavaScript code. |
|
||
|
||
:::warning
|
||
The comparison described in the table above may not be applicable to large and complex applications since there are so many factors that can impact performance metrics.
|
||
:::
|
||
|
||
## What's next
|
||
|
||
- To start a new project with CSS theme variables, check out the [basic usage guide](/material-ui/customization/css-theme-variables/usage/).
|
||
- For theming and customization, check out the [how-to guide](/material-ui/customization/css-theme-variables/configuration/).
|