This document explains the styling and theming architecture in the MUI monorepo. It covers the styled engine abstraction that allows switching between Emotion and styled-components, the theme system that provides design tokens across all component libraries, and the CSS variables implementation that enables runtime theme customization. For information about specific component styling and customization patterns, see Core Component Libraries.
The MUI styling system is built on a layered architecture that separates the styling API from the underlying CSS-in-JS implementation. Recent updates include support for Pigment CSS, a zero-runtime CSS-in-JS solution that supports React Server Components (RSC).
Sources: packages/mui-material/src/styles/index.d.ts47-75 packages/mui-system/src/index.d.ts83-87 packages/mui-system/src/index.js48-51
MUI uses a "styled engine" abstraction to remain agnostic of the underlying CSS-in-JS library. This allows users to choose between Emotion (default) and styled-components.
This package serves as a wrapper around Emotion. It exports the styled API and GlobalStyles component used throughout the library.
styled, GlobalStyles, StyledEngineProvider, keyframes.StyledEngineProvider is re-exported from @mui/system packages/mui-system/src/index.js1styled function packages/mui-system/src/index.d.ts86 is the primary utility for creating styled components.An alternative engine that wraps styled-components. It provides a compatible interface so that the entire MUI suite can run on styled-components by simply aliasing the package in the bundler.
Pigment CSS is a build-time CSS-in-JS engine. Unlike Emotion, it extracts styles into static CSS files during the build process, eliminating the runtime overhead and enabling support for React Server Components.
Sources: packages/mui-system/src/index.js1-2 packages/mui-system/src/index.d.ts49-56 packages/mui-system/src/index.d.ts86-87
MUI's theme system has evolved from a static JavaScript object to a dynamic system powered by CSS custom properties (variables).
A theme is created using createTheme docs/data/material/customization/theming/theming.md157 or extendTheme packages/mui-material/src/styles/index.d.ts131 (for CSS variables). It contains tokens for:
palette object can be customized with main, light, dark, and contrastText tokens docs/data/material/customization/palette/palette.md73-94Typography component uses the Material Design typographic scale docs/data/material/components/typography/typography.md67The ThemeProvider component packages/mui-material/src/styles/index.d.ts84 is used to inject a custom theme into an application docs/data/material/customization/theming/theming.md17-20 To generate CSS variables from the theme, cssVariables must be set to true in the theme configuration docs/data/material/customization/theming/theming.md127-131 This generates a global stylesheet with CSS theme variables, which components then use instead of raw values docs/data/material/customization/theming/theming.md139-151 The default variable prefix is --mui, but it can be customized via cssVarPrefix docs/data/material/customization/css-theme-variables/configuration.md6-23
MUI supports multiple color schemes, including light (default) and dark docs/data/material/customization/dark-mode/dark-mode.md3 The colorSchemes node in createTheme() enables automatic switching based on user preference and synchronization across tabs docs/data/material/customization/dark-mode/dark-mode.md67-91 The useColorScheme hook allows users to toggle between modes docs/data/material/customization/dark-mode/dark-mode.md121-122
localStorage by default via the storageManager docs/data/material/customization/dark-mode/dark-mode.md130-131InitColorSchemeScript is used to apply the correct theme attribute (data-mui-color-scheme or a custom class) before the page renders to prevent SSR flickering docs/data/material/customization/css-theme-variables/configuration.md167-170theme.applyStyles() function packages/mui-system/src/createTheme/applyStyles.ts1-2 is recommended for applying styles specifically for dark mode to ensure compatibility with CSS variables docs/data/material/customization/css-theme-variables/configuration.md133-165For details, see Theme System and CSS Variables.
Sources: docs/data/material/customization/theming/theming.md17-20 docs/data/material/customization/theming/theming.md127-131 docs/data/material/customization/css-theme-variables/configuration.md6-23 docs/data/material/customization/dark-mode/dark-mode.md67-91 docs/data/material/customization/css-theme-variables/configuration.md167-170 packages/mui-material/src/styles/index.d.ts84 packages/mui-material/src/styles/index.d.ts131 packages/mui-system/src/createTheme/applyStyles.ts1-2
While all products use the underlying @mui/system infrastructure, they implement specific providers and prefixes:
| Product | Provider | Theme Function | Default Prefix |
|---|---|---|---|
| Material UI | ThemeProvider | createTheme / extendTheme | --mui- |
| Joy UI | CssVarsProvider | extendTheme | --joy- |
| MUI System | ThemeProvider | createTheme | (Customizable) |
In the monorepo's documentation, BrandingCssVarsProvider is used to apply MUI's corporate identity across all pages. It internally merges brand tokens with the standard Material UI theme to maintain consistency across marketing and documentation pages.
Sources: packages/mui-material/src/styles/index.d.ts84 packages/mui-material/src/styles/index.d.ts131 docs/data/material/customization/css-theme-variables/configuration.md6-14 packages/mui-system/src/index.d.ts114-115
Refresh this wiki