Skip to content
🚀 Material UI and MUI X v9 are out! Check out the announcement blogpost.
+

Upgrade to v10

This guide explains how to upgrade from Material UI v9 to v10.

Breaking changes

Theme

CSS theme variables are enabled by default

createTheme() now generates CSS theme variables by default. Components read theme values such as colors, shadows, and spacing from CSS variables, for example var(--mui-palette-primary-main).

To keep the previous behavior, set cssVariables to false:

 const theme = createTheme({
+  cssVariables: false,
 });

The theme types follow the same default: theme.vars is always defined, the palette includes channel tokens such as theme.palette.primary.mainChannel, and the ThemeProvider accepts props such as colorSchemeNode and disableNestedContext. The @mui/material/themeCssVarsAugmentation import is no longer needed and can be removed. If you set cssVariables: false, remove these from the types with module augmentation:

declare module '@mui/material/styles' {
  interface CssThemeVariables {
    enabled: false;
  }
}

If your theme defines both light and dark color schemes:

  • The color scheme follows the prefers-color-scheme media query by default, so setMode() from useColorScheme() has no effect. To toggle the mode manually, set colorSchemeSelector as described in Toggling dark mode manually.
  • The theme object no longer changes between modes. Read values from theme.vars or use theme.applyStyles(), or pass the forceThemeRerender prop to the ThemeProvider as described in Force theme recalculation between modes.

theme.spacing() returns a calc() expression based on the --mui-spacing variable, for example calc(2 * var(--mui-spacing, 8px)), instead of 16px.