Breaking changes in v5, part one: styles and themes

This is a reference guide to the breaking changes introduced in Material UI v5, and how to migrating from v4. This part covers changes to styling and theming.

Material UI v5 migration

Getting started
Breaking changes part one: style and theme 👈 you are here
Breaking changes part two: components
Migrating from JSS
Troubleshooting

Breaking changes, part one

Material UI v5 introduces a number of breaking changes from v4. Many of these changes can be resolved automatically using the codemods described in the main migration guide.

The following document lists all breaking changes related to styles and themes in v5 and how to address them.

After you're finished here, please move on to Breaking changes in v5 part two: components to continue the migration process.

Migrate theme styleOverrides to Emotion

Although your style overrides defined in the theme may partially work, there is an important difference regarding how the nested elements are styled.

The $ syntax (local rule reference) used with JSS will not work with Emotion. You need to replace those selectors with a valid class selector.

Replace state class names

<span class="token unchanged"><span class="token prefix unchanged"> </span><span class="token line">const theme = createTheme({
</span><span class="token prefix unchanged"> </span><span class="token line">  components: {
</span><span class="token prefix unchanged"> </span><span class="token line">    MuiOutlinedInput: {
</span><span class="token prefix unchanged"> </span><span class="token line">      styleOverrides: {
</span><span class="token prefix unchanged"> </span><span class="token line">        root: {
</span></span><span class="token deleted-sign deleted"><span class="token prefix deleted">-</span><span class="token line">          '&amp;$focused': {
</span></span><span class="token inserted-sign inserted"><span class="token prefix inserted">+</span><span class="token line">          '&amp;.Mui-focused': {
</span></span><span class="token unchanged"><span class="token prefix unchanged"> </span><span class="token line">            borderWidth: 1,
</span><span class="token prefix unchanged"> </span><span class="token line">          }
</span><span class="token prefix unchanged"> </span><span class="token line">        }
</span><span class="token prefix unchanged"> </span><span class="token line">      }
</span><span class="token prefix unchanged"> </span><span class="token line">    }
</span><span class="token prefix unchanged"> </span><span class="token line">  }
</span><span class="token prefix unchanged"> </span><span class="token line">});</span></span>

Replace nested classes selectors with global class names

<span class="token unchanged"><span class="token prefix unchanged"> </span><span class="token line">const theme = createTheme({
</span><span class="token prefix unchanged"> </span><span class="token line">  components: {
</span><span class="token prefix unchanged"> </span><span class="token line">    MuiOutlinedInput: {
</span><span class="token prefix unchanged"> </span><span class="token line">      styleOverrides: {
</span><span class="token prefix unchanged"> </span><span class="token line">        root: {
</span></span><span class="token deleted-sign deleted"><span class="token prefix deleted">-</span><span class="token line">          '&amp; $notchedOutline': {
</span></span><span class="token inserted-sign inserted"><span class="token prefix inserted">+</span><span class="token line">          '&amp; .MuiOutlinedInput-notchedOutline': {
</span></span><span class="token unchanged"><span class="token prefix unchanged"> </span><span class="token line">            borderWidth: 1,
</span><span class="token prefix unchanged"> </span><span class="token line">          }
</span><span class="token prefix unchanged"> </span><span class="token line">        }
</span><span class="token prefix unchanged"> </span><span class="token line">      }
</span><span class="token prefix unchanged"> </span><span class="token line">    }
</span><span class="token prefix unchanged"> </span><span class="token line">  }
</span><span class="token prefix unchanged"> </span><span class="token line">});</span></span>

<span class="token inserted-sign inserted"><span class="token prefix inserted">+</span><span class="token line">import { outlinedInputClasses } from '@mui/material/OutlinedInput';
</span></span>
<span class="token unchanged"><span class="token prefix unchanged"> </span><span class="token line">const theme = createTheme({
</span><span class="token prefix unchanged"> </span><span class="token line">  components: {
</span><span class="token prefix unchanged"> </span><span class="token line">    MuiOutlinedInput: {
</span><span class="token prefix unchanged"> </span><span class="token line">      styleOverrides: {
</span><span class="token prefix unchanged"> </span><span class="token line">        root: {
</span></span><span class="token deleted-sign deleted"><span class="token prefix deleted">-</span><span class="token line">          '&amp; $notchedOutline': {
</span></span><span class="token inserted-sign inserted"><span class="token prefix inserted">+</span><span class="token line">          [`&amp; .${outlinedInputClasses.notchedOutline}`]: {
</span></span><span class="token unchanged"><span class="token prefix unchanged"> </span><span class="token line">            borderWidth: 1,
</span><span class="token prefix unchanged"> </span><span class="token line">          }
</span><span class="token prefix unchanged"> </span><span class="token line">        }
</span><span class="token prefix unchanged"> </span><span class="token line">      }
</span><span class="token prefix unchanged"> </span><span class="token line">    }
</span><span class="token prefix unchanged"> </span><span class="token line">  }
</span><span class="token prefix unchanged"> </span><span class="token line">});</span></span>

Take a look at the complete list of global state classnames available.

ref

Refactor non-ref-forwarding class components

Support for non-ref-forwarding class components in the component prop or as immediate children has been dropped.

If you were using unstable_createStrictModeTheme or didn't see any warnings related to findDOMNode in React.StrictMode then you don't need to take any further action.

Otherwise check out the Caveat with refs section in the Composition guide to find out how to migrate. This change affects almost all components where you're using the component prop or passing children to components that require children to be elements (e.g. <MenuList><CustomMenuItem /></MenuList>).

Fix ref type specificity

For some components, you may get a type error when passing ref. To avoid the error, you should use a specific element type. For example, Card expects the type of ref to be HTMLDivElement, and ListItem expects its ref type to be HTMLLIElement.

Here is an example:

<span class="token unchanged"><span class="token prefix unchanged"> </span><span class="token line">import * as React from 'react';
</span><span class="token prefix unchanged"> </span><span class="token line">import Card from '@mui/material/Card';
</span><span class="token prefix unchanged"> </span><span class="token line">import ListItem from '@mui/material/ListItem';
</span></span>
<span class="token unchanged"><span class="token prefix unchanged"> </span><span class="token line">export default function SpecificRefType() {
</span></span><span class="token deleted-sign deleted"><span class="token prefix deleted">-</span><span class="token line">  const cardRef = React.useRef&lt;HTMLElement>(null);
</span></span><span class="token inserted-sign inserted"><span class="token prefix inserted">+</span><span class="token line">  const cardRef = React.useRef&lt;HTMLDivElement>(null);
</span></span>
<span class="token deleted-sign deleted"><span class="token prefix deleted">-</span><span class="token line">  const listItemRef = React.useRef&lt;HTMLElement>(null);
</span></span><span class="token inserted-sign inserted"><span class="token prefix inserted">+</span><span class="token line">  const listItemRef = React.useRef&lt;HTMLLIElement>(null);
</span></span><span class="token unchanged"><span class="token prefix unchanged"> </span><span class="token line">  return (
</span><span class="token prefix unchanged"> </span><span class="token line">    &lt;div>
</span><span class="token prefix unchanged"> </span><span class="token line">      &lt;Card ref={cardRef}>&lt;/Card>
</span><span class="token prefix unchanged"> </span><span class="token line">      &lt;ListItem ref={listItemRef}>&lt;/ListItem>
</span><span class="token prefix unchanged"> </span><span class="token line">    &lt;/div>
</span><span class="token prefix unchanged"> </span><span class="token line">  );
</span><span class="token prefix unchanged"> </span><span class="token line">}</span></span>

Here are the specific element types that each component expects:

@mui/material

Accordion - HTMLDivElement
Alert - HTMLDivElement
Avatar - HTMLDivElement
ButtonGroup - HTMLDivElement
Card - HTMLDivElement
Dialog - HTMLDivElement
ImageList - HTMLUListElement
List - HTMLUListElement
Tab - HTMLDivElement
Tabs - HTMLDivElement
ToggleButton - HTMLButtonElement

@mui/lab

Timeline - HTMLUListElement

Style library

✅ Adjust CSS injection order

The style library used by default in v5 is Emotion.

If you were using JSS for the style overrides of Material UI components—for example, those created by makeStyles—you will need to take care of the CSS injection order. JSS <style>' elements need to be injected in the <head> after Emotion <style>' elements.

To do so, you need to have the StyledEngineProvider with the injectFirst option at the top of your component tree, as shown here:

<span class="token keyword">import</span> <span class="token operator">*</span> <span class="token keyword">as</span> React <span class="token keyword">from</span> <span class="token string">'react'</span><span class="token punctuation">;</span>
<span class="token keyword">import</span> <span class="token punctuation">{</span> StyledEngineProvider <span class="token punctuation">}</span> <span class="token keyword">from</span> <span class="token string">'@mui/material/styles'</span><span class="token punctuation">;</span>

<span class="token keyword">export</span> <span class="token keyword">default</span> <span class="token keyword">function</span> <span class="token function">GlobalCssPriority</span><span class="token punctuation">(</span><span class="token punctuation">)</span> <span class="token punctuation">{</span>
  <span class="token keyword">return</span> <span class="token punctuation">(</span>
    <span class="token punctuation">{</span><span class="token comment">/* Inject Emotion before JSS */</span><span class="token punctuation">}</span>
    <span class="token tag"><span class="token tag"><span class="token punctuation">&lt;</span><span class="token class-name">StyledEngineProvider</span></span> <span class="token attr-name">injectFirst</span><span class="token punctuation">></span></span>
      <span class="token punctuation">{</span><span class="token comment">/* Your component tree. Now you can override Material UI's styles. */</span><span class="token punctuation">}</span>
    <span class="token tag"><span class="token tag"><span class="token punctuation">&lt;/</span><span class="token class-name">StyledEngineProvider</span></span><span class="token punctuation">></span></span>
  <span class="token punctuation">)</span><span class="token punctuation">;</span>
<span class="token punctuation">}</span>

✅ Add prepend to createCache

If you have a custom cache and are using Emotion to style your app, it will override the cache provided by Material UI.

To correct the injection order, add the prepend option to createCache, as shown below:

<span class="token unchanged"><span class="token prefix unchanged"> </span><span class="token line">import * as React from 'react';
</span><span class="token prefix unchanged"> </span><span class="token line">import { CacheProvider } from '@emotion/react';
</span><span class="token prefix unchanged"> </span><span class="token line">import createCache from '@emotion/cache';
</span></span>
<span class="token unchanged"><span class="token prefix unchanged"> </span><span class="token line">const cache = createCache({
</span><span class="token prefix unchanged"> </span><span class="token line">  key: 'css',
</span></span><span class="token inserted-sign inserted"><span class="token prefix inserted">+</span><span class="token line">  prepend: true,
</span></span><span class="token unchanged"><span class="token prefix unchanged"> </span><span class="token line">});
</span></span>
<span class="token unchanged"><span class="token prefix unchanged"> </span><span class="token line">export default function PlainCssPriority() {
</span><span class="token prefix unchanged"> </span><span class="token line">  return (
</span><span class="token prefix unchanged"> </span><span class="token line">    &lt;CacheProvider value={cache}>
</span><span class="token prefix unchanged"> </span><span class="token line">      {/* Your component tree. Now you can override Material UI's styles. */}
</span><span class="token prefix unchanged"> </span><span class="token line">    &lt;/CacheProvider>
</span><span class="token prefix unchanged"> </span><span class="token line">  );
</span><span class="token prefix unchanged"> </span><span class="token line">}</span></span>

Theme structure

✅ Add adaptV4Theme helper

The structure of the theme has changed in v5. You need to update its shape. For a smoother transition, the adaptV4Theme helper allows you to iteratively upgrade some of the theme changes to the new theme structure.

<span class="token deleted-sign deleted"><span class="token prefix deleted">-</span><span class="token line">import { createMuiTheme } from '@mui/material/styles';
</span></span><span class="token inserted-sign inserted"><span class="token prefix inserted">+</span><span class="token line">import { createTheme, adaptV4Theme } from '@mui/material/styles';
</span></span>
<span class="token deleted-sign deleted"><span class="token prefix deleted">-</span><span class="token line">const theme = createMuiTheme({
</span></span><span class="token inserted-sign inserted"><span class="token prefix inserted">+</span><span class="token line">const theme = createTheme(adaptV4Theme({
</span></span><span class="token unchanged"><span class="token prefix unchanged"> </span><span class="token line">  // v4 theme
</span></span><span class="token deleted-sign deleted"><span class="token prefix deleted">-</span><span class="token line">});
</span></span><span class="token inserted-sign inserted"><span class="token prefix inserted">+</span><span class="token line">}));</span></span>

The following changes are supported by the adapter:

Remove gutters

The "gutters" abstraction hasn't proven to be used frequently enough to be valuable.

<span class="token deleted-sign deleted"><span class="token prefix deleted">-</span><span class="token line">theme.mixins.gutters(),
</span></span><span class="token inserted-sign inserted"><span class="token prefix inserted">+</span><span class="token line">paddingLeft: theme.spacing(2),
</span><span class="token prefix inserted">+</span><span class="token line">paddingRight: theme.spacing(2),
</span><span class="token prefix inserted">+</span><span class="token line">[theme.breakpoints.up('sm')]: {
</span><span class="token prefix inserted">+</span><span class="token line">  paddingLeft: theme.spacing(3),
</span><span class="token prefix inserted">+</span><span class="token line">  paddingRight: theme.spacing(3),
</span><span class="token prefix inserted">+</span><span class="token line">},</span></span>

✅ Remove px suffix

theme.spacing now returns single values with px units by default. This change improves the integration with styled-components & Emotion.

Before:

theme<span class="token punctuation">.</span><span class="token function">spacing</span><span class="token punctuation">(</span><span class="token parameter"><span class="token number">2</span></span><span class="token punctuation">)</span> <span class="token operator">=></span> <span class="token number">16</span>

After:

theme<span class="token punctuation">.</span><span class="token function">spacing</span><span class="token punctuation">(</span><span class="token parameter"><span class="token number">2</span></span><span class="token punctuation">)</span> <span class="token operator">=></span> <span class="token string">'16px'</span>

✅ Rename theme.palette.type

The theme.palette.type key was renamed to theme.palette.mode, to better follow the "dark mode" terminology that is usually used for describing this feature.

<span class="token unchanged"><span class="token prefix unchanged"> </span><span class="token line">import { createTheme } from '@mui/material/styles';
</span></span><span class="token deleted-sign deleted"><span class="token prefix deleted">-</span><span class="token line">const theme = createTheme({ palette: { type: 'dark' } }),
</span></span><span class="token inserted-sign inserted"><span class="token prefix inserted">+</span><span class="token line">const theme = createTheme({ palette: { mode: 'dark' } }),</span></span>

Change default theme.palette.info colors

The default theme.palette.info colors were changed to pass the AA accessibility standard contrast ratio in both light and dark modes.

<span class="token unchanged"><span class="token prefix unchanged"> </span><span class="token line"> info = {
</span></span><span class="token deleted-sign deleted"><span class="token prefix deleted">-</span><span class="token line">  main: cyan[500],
</span></span><span class="token inserted-sign inserted"><span class="token prefix inserted">+</span><span class="token line">  main: lightBlue[700], // lightBlue[400] in "dark" mode
</span></span>
<span class="token deleted-sign deleted"><span class="token prefix deleted">-</span><span class="token line">  light: cyan[300],
</span></span><span class="token inserted-sign inserted"><span class="token prefix inserted">+</span><span class="token line">  light: lightBlue[500], // lightBlue[300] in "dark" mode
</span></span>
<span class="token deleted-sign deleted"><span class="token prefix deleted">-</span><span class="token line">  dark: cyan[700],
</span></span><span class="token inserted-sign inserted"><span class="token prefix inserted">+</span><span class="token line">  dark: lightBlue[900], // lightBlue[700] in "dark" mode
</span></span><span class="token unchanged"><span class="token prefix unchanged"> </span><span class="token line"> }</span></span>

Change default theme.palette.success colors

The default theme.palette.success colors were changed to pass the AA accessibility standard contrast ratio in both light and dark modes.

<span class="token unchanged"><span class="token prefix unchanged"> </span><span class="token line"> success = {
</span></span><span class="token deleted-sign deleted"><span class="token prefix deleted">-</span><span class="token line">  main: green[500],
</span></span><span class="token inserted-sign inserted"><span class="token prefix inserted">+</span><span class="token line">  main: green[800], // green[400] in "dark" mode
</span></span>
<span class="token deleted-sign deleted"><span class="token prefix deleted">-</span><span class="token line">  light: green[300],
</span></span><span class="token inserted-sign inserted"><span class="token prefix inserted">+</span><span class="token line">  light: green[500], // green[300] in "dark" mode
</span></span>
<span class="token deleted-sign deleted"><span class="token prefix deleted">-</span><span class="token line">  dark: green[700],
</span></span><span class="token inserted-sign inserted"><span class="token prefix inserted">+</span><span class="token line">  dark: green[900], // green[700] in "dark" mode
</span></span><span class="token unchanged"><span class="token prefix unchanged"> </span><span class="token line"> }</span></span>

Change default theme.palette.warning colors

The default theme.palette.warning colors were changed to pass the AA accessibility standard contrast ratio in both light and dark modes.

<span class="token unchanged"><span class="token prefix unchanged"> </span><span class="token line"> warning = {
</span></span><span class="token deleted-sign deleted"><span class="token prefix deleted">-</span><span class="token line">  main: orange[500],
</span></span><span class="token inserted-sign inserted"><span class="token prefix inserted">+</span><span class="token line">  main: '#ED6C02', // orange[400] in "dark" mode
</span></span>
<span class="token deleted-sign deleted"><span class="token prefix deleted">-</span><span class="token line">  light: orange[300],
</span></span><span class="token inserted-sign inserted"><span class="token prefix inserted">+</span><span class="token line">  light: orange[500], // orange[300] in "dark" mode
</span></span>
<span class="token deleted-sign deleted"><span class="token prefix deleted">-</span><span class="token line">  dark: orange[700],
</span></span><span class="token inserted-sign inserted"><span class="token prefix inserted">+</span><span class="token line">  dark: orange[900], // orange[700] in "dark" mode
</span></span><span class="token unchanged"><span class="token prefix unchanged"> </span><span class="token line"> }</span></span>

Restore theme.palette.text.hint key (if needed)

The theme.palette.text.hint key was unused in Material UI components, and has been removed. If you depend on it, you can add it back:

<span class="token unchanged"><span class="token prefix unchanged"> </span><span class="token line"> import { createTheme } from '@mui/material/styles';
</span></span>
<span class="token deleted-sign deleted"><span class="token prefix deleted">-</span><span class="token line">const theme = createTheme(),
</span></span><span class="token inserted-sign inserted"><span class="token prefix inserted">+</span><span class="token line">const theme = createTheme({
</span><span class="token prefix inserted">+</span><span class="token line">  palette: { text: { hint: 'rgba(0, 0, 0, 0.38)' } },
</span><span class="token prefix inserted">+</span><span class="token line">});</span></span>

Restructure component definitions

The component definitions in the theme were restructured under the components key to make them easier to find.

1. props

<span class="token unchanged"><span class="token prefix unchanged"> </span><span class="token line">import { createTheme } from '@mui/material/styles';
</span></span>
<span class="token unchanged"><span class="token prefix unchanged"> </span><span class="token line">const theme = createTheme({
</span></span><span class="token deleted-sign deleted"><span class="token prefix deleted">-</span><span class="token line">  props: {
</span><span class="token prefix deleted">-</span><span class="token line">    MuiButton: {
</span><span class="token prefix deleted">-</span><span class="token line">      disableRipple: true,
</span><span class="token prefix deleted">-</span><span class="token line">    },
</span><span class="token prefix deleted">-</span><span class="token line">  },
</span></span><span class="token inserted-sign inserted"><span class="token prefix inserted">+</span><span class="token line">  components: {
</span><span class="token prefix inserted">+</span><span class="token line">    MuiButton: {
</span><span class="token prefix inserted">+</span><span class="token line">      defaultProps: {
</span><span class="token prefix inserted">+</span><span class="token line">        disableRipple: true,
</span><span class="token prefix inserted">+</span><span class="token line">      },
</span><span class="token prefix inserted">+</span><span class="token line">    },
</span><span class="token prefix inserted">+</span><span class="token line">  },
</span></span><span class="token unchanged"><span class="token prefix unchanged"> </span><span class="token line">});</span></span>

2. overrides

<span class="token unchanged"><span class="token prefix unchanged"> </span><span class="token line">import { createTheme } from '@mui/material/styles';
</span></span>
<span class="token unchanged"><span class="token prefix unchanged"> </span><span class="token line">const theme = createTheme({
</span></span><span class="token deleted-sign deleted"><span class="token prefix deleted">-</span><span class="token line">  overrides: {
</span><span class="token prefix deleted">-</span><span class="token line">    MuiButton: {
</span><span class="token prefix deleted">-</span><span class="token line">      root: { padding: 0 },
</span><span class="token prefix deleted">-</span><span class="token line">    },
</span><span class="token prefix deleted">-</span><span class="token line">  },
</span></span><span class="token inserted-sign inserted"><span class="token prefix inserted">+</span><span class="token line">  components: {
</span><span class="token prefix inserted">+</span><span class="token line">    MuiButton: {
</span><span class="token prefix inserted">+</span><span class="token line">      styleOverrides: {
</span><span class="token prefix inserted">+</span><span class="token line">        root: { padding: 0 },
</span><span class="token prefix inserted">+</span><span class="token line">      },
</span><span class="token prefix inserted">+</span><span class="token line">    },
</span><span class="token prefix inserted">+</span><span class="token line">  },
</span></span><span class="token unchanged"><span class="token prefix unchanged"> </span><span class="token line">});</span></span>

@mui/styles

Update ThemeProvider import

If you are using the utilities from @mui/styles together with the @mui/material, you should replace the use of ThemeProvider from @mui/styles with the one exported from @mui/material/styles.

This way, the theme provided in the context will be available in both the styling utilities exported from @mui/styles, like makeStyles, withStyles, etc., along with the Material UI components.

<span class="token deleted-sign deleted"><span class="token prefix deleted">-</span><span class="token line">import { ThemeProvider } from '@mui/styles';
</span></span><span class="token inserted-sign inserted"><span class="token prefix inserted">+</span><span class="token line">import { ThemeProvider } from '@mui/material/styles';</span></span>

Make sure to add a ThemeProvider at the root of your application, as the defaultTheme is no longer available in the utilities coming from @mui/styles.

✅ Add module augmentation for DefaultTheme (TypeScript)

The @mui/styles package is no longer part of @mui/material/styles.

If you are using @mui/styles together with @mui/material you need to add a module augmentation for the DefaultTheme.

<span class="token comment">// in the file where you are creating the theme (invoking the function `createTheme()`)</span>
<span class="token keyword">import</span> <span class="token punctuation">{</span> Theme <span class="token punctuation">}</span> <span class="token keyword">from</span> <span class="token string">'@mui/material/styles'</span><span class="token punctuation">;</span>

declare module <span class="token string">'@mui/styles'</span> <span class="token punctuation">{</span>
  <span class="token keyword">interface</span> <span class="token class-name">DefaultTheme</span> <span class="token keyword">extends</span> <span class="token class-name">Theme</span> <span class="token punctuation">{</span><span class="token punctuation">}</span>
<span class="token punctuation">}</span>

@mui/material/colors

✅ Change color imports

Nested imports of more than one level are private. For example, you can no longer import red from @mui/material/colors/red.

<span class="token deleted-sign deleted"><span class="token prefix deleted">-</span><span class="token line">import red from '@mui/material/colors/red';
</span></span><span class="token inserted-sign inserted"><span class="token prefix inserted">+</span><span class="token line">import { red } from '@mui/material/colors';</span></span>

@mui/material/styles

✅ Rename fade to alpha

fade was renamed to alpha to better describe its functionality.

The previous name caused confusion when the input color already had an alpha value. The helper overrides the alpha value of the color.

<span class="token deleted-sign deleted"><span class="token prefix deleted">-</span><span class="token line">import { fade } from '@mui/material/styles';
</span></span><span class="token inserted-sign inserted"><span class="token prefix inserted">+</span><span class="token line">import { alpha } from '@mui/material/styles';
</span></span>
<span class="token unchanged"><span class="token prefix unchanged"> </span><span class="token line"> const classes = makeStyles(theme => ({
</span></span><span class="token deleted-sign deleted"><span class="token prefix deleted">-</span><span class="token line">  backgroundColor: fade(theme.palette.primary.main, theme.palette.action.selectedOpacity),
</span></span><span class="token inserted-sign inserted"><span class="token prefix inserted">+</span><span class="token line">  backgroundColor: alpha(theme.palette.primary.main, theme.palette.action.selectedOpacity),
</span></span><span class="token unchanged"><span class="token prefix unchanged"> </span><span class="token line"> }));</span></span>

✅ Update createStyles import

The createStyles function from @mui/material/styles was moved to the one exported from @mui/styles. It is necessary for removing the dependency on @mui/styles in the Material UI npm package.

<span class="token deleted-sign deleted"><span class="token prefix deleted">-</span><span class="token line">import { createStyles } from '@mui/material/styles';
</span></span><span class="token inserted-sign inserted"><span class="token prefix inserted">+</span><span class="token line">import { createStyles } from '@mui/styles';</span></span>

✅ Update createGenerateClassName import

The createGenerateClassName function is no longer exported from @mui/material/styles. You should import it directly from @mui/styles.

<span class="token deleted-sign deleted"><span class="token prefix deleted">-</span><span class="token line">import { createGenerateClassName } from '@mui/material/styles';
</span></span><span class="token inserted-sign inserted"><span class="token prefix inserted">+</span><span class="token line">import { createGenerateClassName } from '@mui/styles';</span></span>

To generate custom class names without using @mui/styles, check out ClassName Generator for more details.

✅ Rename createMuiTheme

The function createMuiTheme was renamed to createTheme to make it more intuitive to use with ThemeProvider.

<span class="token deleted-sign deleted"><span class="token prefix deleted">-</span><span class="token line">import { createMuiTheme } from '@mui/material/styles';
</span></span><span class="token inserted-sign inserted"><span class="token prefix inserted">+</span><span class="token line">import { createTheme } from '@mui/material/styles';
</span></span>
<span class="token deleted-sign deleted"><span class="token prefix deleted">-</span><span class="token line">const theme = createMuiTheme({
</span></span><span class="token inserted-sign inserted"><span class="token prefix inserted">+</span><span class="token line">const theme = createTheme({</span></span>

✅ Update MuiThemeProvider import

The MuiThemeProvider component is no longer exported from @mui/material/styles. Use ThemeProvider instead.

<span class="token deleted-sign deleted"><span class="token prefix deleted">-</span><span class="token line">import { MuiThemeProvider } from '@mui/material/styles';
</span></span><span class="token inserted-sign inserted"><span class="token prefix inserted">+</span><span class="token line">import { ThemeProvider } from '@mui/material/styles';</span></span>

✅ Update jssPreset import

The jssPreset object is no longer exported from @mui/material/styles. You should import it directly from @mui/styles.

<span class="token deleted-sign deleted"><span class="token prefix deleted">-</span><span class="token line">import { jssPreset } from '@mui/material/styles';
</span></span><span class="token inserted-sign inserted"><span class="token prefix inserted">+</span><span class="token line">import { jssPreset } from '@mui/styles';</span></span>

✅ Update `makeStyles` import

The makeStyles JSS utility is no longer exported from @mui/material/styles. You can use @mui/styles/makeStyles instead.

Make sure to add a ThemeProvider at the root of your application, as the defaultTheme is no longer available.

If you are using this utility together with @mui/material, it's recommended that you use the ThemeProvider component from @mui/material/styles instead.

<span class="token deleted-sign deleted"><span class="token prefix deleted">-</span><span class="token line">import { makeStyles } from '@mui/material/styles';
</span></span><span class="token inserted-sign inserted"><span class="token prefix inserted">+</span><span class="token line">import { makeStyles } from '@mui/styles';
</span><span class="token prefix inserted">+</span><span class="token line">import { createTheme, ThemeProvider } from '@mui/material/styles';
</span></span>
<span class="token inserted-sign inserted"><span class="token prefix inserted">+</span><span class="token line">const theme = createTheme();
</span></span><span class="token unchanged"><span class="token prefix unchanged"> </span><span class="token line"> const useStyles = makeStyles((theme) => ({
</span><span class="token prefix unchanged"> </span><span class="token line">   background: theme.palette.primary.main,
</span><span class="token prefix unchanged"> </span><span class="token line"> }));
</span><span class="token prefix unchanged"> </span><span class="token line"> function Component() {
</span><span class="token prefix unchanged"> </span><span class="token line">   const classes = useStyles();
</span><span class="token prefix unchanged"> </span><span class="token line">   return &lt;div className={classes.root} />
</span><span class="token prefix unchanged"> </span><span class="token line"> }
</span></span>
<span class="token unchanged"><span class="token prefix unchanged"> </span><span class="token line"> // In the root of your app
</span><span class="token prefix unchanged"> </span><span class="token line"> function App(props) {
</span></span><span class="token deleted-sign deleted"><span class="token prefix deleted">-</span><span class="token line">  return &lt;Component />;
</span></span><span class="token inserted-sign inserted"><span class="token prefix inserted">+</span><span class="token line">  return &lt;ThemeProvider theme={theme}>&lt;Component {...props} />&lt;/ThemeProvider>;
</span></span><span class="token unchanged"><span class="token prefix unchanged"> </span><span class="token line"> }</span></span>

✅ Update ServerStyleSheets import

The ServerStyleSheets component is no longer exported from @mui/material/styles. You should import it directly from @mui/styles.

<span class="token deleted-sign deleted"><span class="token prefix deleted">-</span><span class="token line">import { ServerStyleSheets } from '@mui/material/styles';
</span></span><span class="token inserted-sign inserted"><span class="token prefix inserted">+</span><span class="token line">import { ServerStyleSheets } from '@mui/styles';</span></span>

styled

The styled JSS utility is no longer exported from @mui/material/styles. You can use the one exported from @mui/styles instead.

Make sure to add a ThemeProvider at the root of your application, as the defaultTheme is no longer available.

If you are using this utility together with @mui/material, it's recommended you use the ThemeProvider component from @mui/material/styles instead.

<span class="token deleted-sign deleted"><span class="token prefix deleted">-</span><span class="token line">import { styled } from '@mui/material/styles';
</span></span><span class="token inserted-sign inserted"><span class="token prefix inserted">+</span><span class="token line">import { styled } from '@mui/styles';
</span><span class="token prefix inserted">+</span><span class="token line">import { createTheme, ThemeProvider } from '@mui/material/styles';
</span></span>
<span class="token inserted-sign inserted"><span class="token prefix inserted">+</span><span class="token line">const theme = createTheme();
</span></span><span class="token unchanged"><span class="token prefix unchanged"> </span><span class="token line"> const MyComponent = styled('div')(({ theme }) => ({ background: theme.palette.primary.main }));
</span></span>
<span class="token unchanged"><span class="token prefix unchanged"> </span><span class="token line"> function App(props) {
</span></span><span class="token deleted-sign deleted"><span class="token prefix deleted">-</span><span class="token line">  return &lt;MyComponent />;
</span></span><span class="token inserted-sign inserted"><span class="token prefix inserted">+</span><span class="token line">  return &lt;ThemeProvider theme={theme}>&lt;MyComponent {...props} />&lt;/ThemeProvider>;
</span></span><span class="token unchanged"><span class="token prefix unchanged"> </span><span class="token line"> }</span></span>

✅ Update StylesProvider import

The StylesProvider component is no longer exported from @mui/material/styles. You should import it directly from @mui/styles.

<span class="token deleted-sign deleted"><span class="token prefix deleted">-</span><span class="token line">import { StylesProvider } from '@mui/material/styles';
</span></span><span class="token inserted-sign inserted"><span class="token prefix inserted">+</span><span class="token line">import { StylesProvider } from '@mui/styles';</span></span>

✅ Update useThemeVariants import

The useThemeVariants hook is no longer exported from @mui/material/styles. You should import it directly from @mui/styles.

<span class="token deleted-sign deleted"><span class="token prefix deleted">-</span><span class="token line">import { useThemeVariants } from '@mui/material/styles';
</span></span><span class="token inserted-sign inserted"><span class="token prefix inserted">+</span><span class="token line">import { useThemeVariants } from '@mui/styles';</span></span>

✅ Update withStyles import

The withStyles JSS utility is no longer exported from @mui/material/styles. You can use @mui/styles/withStyles instead.

Make sure to add a ThemeProvider at the root of your application, as the defaultTheme is no longer available.

If you are using this utility together with @mui/material, you should use the ThemeProvider component from @mui/material/styles instead.

<span class="token deleted-sign deleted"><span class="token prefix deleted">-</span><span class="token line">import { withStyles } from '@mui/material/styles';
</span></span><span class="token inserted-sign inserted"><span class="token prefix inserted">+</span><span class="token line">import { withStyles } from '@mui/styles';
</span><span class="token prefix inserted">+</span><span class="token line">import { createTheme, ThemeProvider } from '@mui/material/styles';
</span></span>
<span class="token inserted-sign inserted"><span class="token prefix inserted">+</span><span class="token line">const defaultTheme = createTheme();
</span></span><span class="token unchanged"><span class="token prefix unchanged"> </span><span class="token line"> const MyComponent = withStyles((props) => {
</span><span class="token prefix unchanged"> </span><span class="token line">   const { classes, className, ...other } = props;
</span><span class="token prefix unchanged"> </span><span class="token line">   return &lt;div className={clsx(className, classes.root)} {...other} />
</span><span class="token prefix unchanged"> </span><span class="token line"> })(({ theme }) => ({ root: { background: theme.palette.primary.main }}));
</span></span>
<span class="token unchanged"><span class="token prefix unchanged"> </span><span class="token line"> function App() {
</span></span><span class="token deleted-sign deleted"><span class="token prefix deleted">-</span><span class="token line">  return &lt;MyComponent />;
</span></span><span class="token inserted-sign inserted"><span class="token prefix inserted">+</span><span class="token line">  return &lt;ThemeProvider theme={defaultTheme}>&lt;MyComponent />&lt;/ThemeProvider>;
</span></span><span class="token unchanged"><span class="token prefix unchanged"> </span><span class="token line"> }</span></span>

✅ Replace innerRef with ref

Replace the innerRef prop with the ref prop. Refs are now automatically forwarded to the inner component.

<span class="token unchanged"><span class="token prefix unchanged"> </span><span class="token line"> import * as React from 'react';
</span><span class="token prefix unchanged"> </span><span class="token line"> import { withStyles } from '@mui/styles';
</span></span>
<span class="token unchanged"><span class="token prefix unchanged"> </span><span class="token line"> const MyComponent = withStyles({
</span><span class="token prefix unchanged"> </span><span class="token line">   root: {
</span><span class="token prefix unchanged"> </span><span class="token line">     backgroundColor: 'red',
</span><span class="token prefix unchanged"> </span><span class="token line">   },
</span><span class="token prefix unchanged"> </span><span class="token line"> })(({ classes }) => &lt;div className={classes.root} />);
</span></span>
<span class="token unchanged"><span class="token prefix unchanged"> </span><span class="token line"> function MyOtherComponent(props) {
</span><span class="token prefix unchanged"> </span><span class="token line">   const ref = React.useRef();
</span></span><span class="token deleted-sign deleted"><span class="token prefix deleted">-</span><span class="token line">  return &lt;MyComponent innerRef={ref} />;
</span></span><span class="token inserted-sign inserted"><span class="token prefix inserted">+</span><span class="token line">  return &lt;MyComponent ref={ref} />;
</span></span><span class="token unchanged"><span class="token prefix unchanged"> </span><span class="token line"> }</span></span>

Update withTheme import

The withTheme HOC utility has been removed from the @mui/material/styles package. You can use @mui/styles/withTheme instead.

Make sure to add a ThemeProvider at the root of your application, as the defaultTheme is no longer available.

If you are using this utility together with @mui/material, it's recommended you use the ThemeProvider component from @mui/material/styles instead.

<span class="token deleted-sign deleted"><span class="token prefix deleted">-</span><span class="token line">import { withTheme } from '@mui/material/styles';
</span></span><span class="token inserted-sign inserted"><span class="token prefix inserted">+</span><span class="token line">import { withTheme } from '@mui/styles';
</span><span class="token prefix inserted">+</span><span class="token line">import { createTheme, ThemeProvider } from '@mui/material/styles';
</span></span>
<span class="token inserted-sign inserted"><span class="token prefix inserted">+</span><span class="token line">const theme = createTheme();
</span></span><span class="token unchanged"><span class="token prefix unchanged"> </span><span class="token line"> const MyComponent = withTheme(({ theme }) => &lt;div>{props.theme.direction}&lt;/div>);
</span></span>
<span class="token unchanged"><span class="token prefix unchanged"> </span><span class="token line"> function App(props) {
</span></span><span class="token deleted-sign deleted"><span class="token prefix deleted">-</span><span class="token line">  return &lt;MyComponent />;
</span></span><span class="token inserted-sign inserted"><span class="token prefix inserted">+</span><span class="token line">  return &lt;ThemeProvider theme={theme}>&lt;MyComponent {...props} />&lt;/ThemeProvider>;
</span></span><span class="token unchanged"><span class="token prefix unchanged"> </span><span class="token line"> }</span></span>

✅ Remove withWidth

This HOC was removed. If you need this feature, you can try the alternative that uses the useMediaQuery hook.

@mui/icons-material

Reduce GitHub icon size

The GitHub icon was reduced in size from 24px to 22px wide to match the size of the other icons.

@material-ui/pickers

We have a dedicated page for migrating @material-ui/pickers to v5.

System

✅ Rename gap props

The following system functions and properties were renamed because they are considered deprecated CSS:

gridGap becomes gap
gridRowGap becomes rowGap
gridColumnGap becomes columnGap

✅ Add spacing units to gap props

Use a spacing unit in gap, rowGap, and columnGap. If you were using a number previously, you need to mention the px to bypass the new transformation with theme.spacing.

<span class="token unchanged"><span class="token prefix unchanged"> </span><span class="token line"> &lt;Box
</span></span><span class="token deleted-sign deleted"><span class="token prefix deleted">-</span><span class="token line">  gap={2}
</span></span><span class="token inserted-sign inserted"><span class="token prefix inserted">+</span><span class="token line">  gap="2px"
</span></span><span class="token unchanged"><span class="token prefix unchanged"> </span><span class="token line"> ></span></span>

Replace css prop with sx to avoid collision with styled-components and Emotion's css prop.

<span class="token deleted-sign deleted"><span class="token prefix deleted">-</span><span class="token line">&lt;Box css={{ color: 'primary.main' }} />
</span></span><span class="token inserted-sign inserted"><span class="token prefix inserted">+</span><span class="token line">&lt;Box sx={{ color: 'primary.main' }} /></span></span>

Breaking changes in v5, part one: styles and themes

Material UI v5 migration

Breaking changes, part one

Migrate theme styleOverrides to Emotion

Replace state class names

Replace nested classes selectors with global class names

ref

Refactor non-ref-forwarding class components

Fix ref type specificity

@mui/material

@mui/lab

Style library

✅ Adjust CSS injection order

✅ Add prepend to createCache

Theme structure

✅ Add adaptV4Theme helper

Remove gutters

✅ Remove px suffix

✅ Rename theme.palette.type

Change default theme.palette.info colors

Change default theme.palette.success colors

Change default theme.palette.warning colors

Restore theme.palette.text.hint key (if needed)

Restructure component definitions

1. props

2. overrides

@mui/styles

Update ThemeProvider import

✅ Add module augmentation for DefaultTheme (TypeScript)

@mui/material/colors

✅ Change color imports

@mui/material/styles

✅ Rename fade to alpha

✅ Update createStyles import

✅ Update createGenerateClassName import

✅ Rename createMuiTheme

✅ Update MuiThemeProvider import

✅ Update jssPreset import

✅ Update makeStyles import

✅ Update ServerStyleSheets import

styled

✅ Update StylesProvider import

✅ Update useThemeVariants import

✅ Update withStyles import

✅ Replace innerRef with ref

Update withTheme import

✅ Remove withWidth

@mui/icons-material

Reduce GitHub icon size

@material-ui/pickers

System

✅ Rename gap props

✅ Add spacing units to gap props

✅ Update `makeStyles` import