Skip to content
🚀 MUI X v6 is out! Discover what's new and get started now!
Edit this page

Migrating to v5: getting started

This guide explains how and why to migrate from Material UI v4 to v5.

Material UI v5 migration

  1. Getting started 👈 you are here
  2. Breaking changes part one: style and theme
  3. Breaking changes part two: components
  4. Migrating from JSS
  5. Troubleshooting

Introduction

This is the first document in a multi-part series to walk you through upgrading your app from Material UI v4 to v5.

We highly recommend running our codemods for efficiency—these will automatically address many of the breaking changes introduced in v5.

One of the biggest changes in v5 is the replacement of JSS for Emotion as a default styling solution.

Note that you may continue to use JSS for adding overrides to the components (e.g. makeStyles, withStyles) even after migrating to v5. Once you've completed the rest of the v5 upgrade, we recommend progressively moving over to the new styling engine.

This process is covered in Migrating from JSS.

Why you should migrate

Material UI v5 includes many bug fixes and improvements over v4.

Chief among these improvements is the new styling engine, which offers significant advancements in performance when it comes to dynamic styles, as well as a more enjoyable developer experience.

Additionally, v5 is the only version that fully supports React 18, so you will need to migrate to take advantage of the latest React features.

To learn more, check out the blog post about the release of Material UI v5.

Supported browsers and Node versions

The targets of the default bundle have changed in v5.

The exact versions will be pinned on release from the browserslist query "> 0.5%, last 2 versions, Firefox ESR, not dead, not IE 11, maintained node versions".

The default bundle supports the following minimum versions:

  • Node 12 (up from 8)
  • Chrome 90 (up from 49)
  • Edge 91 (up from 14)
  • Firefox 78 (up from 52)
  • Safari 14 (macOS) and 12.5 (iOS) (up from 10)
  • and more (see .browserslistrc (stable entry))

Material UI no longer supports IE 11. If you need to support IE 11, check out our legacy bundle.

Update React & TypeScript version

Update React

The minimum supported version of React has been increased from v16.8.0 to v17.0.0.

If you are using a React version below 17.0.0, update your packages to at least v4.11.2 for Material UI and v17.0.0 for React.

With npm:

<span class="token function">npm</span> <span class="token function">install</span> @material-ui/core@^4.11.2 react@^17.0.0

With yarn:

<span class="token function">yarn</span> upgrade @material-ui/core@^4.11.2 react@^17.0.0

Update TypeScript

The minimum supported version of TypeScript has been increased from v3.2 to v3.5.

If your project includes these packages, you'll need to update them:

  • react-scripts
  • @types/react
  • @types/react-dom

Set up ThemeProvider

Before upgrading to v5, please make sure that ThemeProvider is defined at the root of your application and in tests—even if you are using the default theme—and useStyles is not called before ThemeProvider.

Eventually you may want to migrate from JSS to Emotion, but in the meantime you can continue to use JSS with the @mui/styles package. This package requires ThemeProvider.

The root of your application should look something like this:

<span class="token keyword">import</span> <span class="token punctuation">{</span> ThemeProvider<span class="token punctuation">,</span> createMuiTheme<span class="token punctuation">,</span> makeStyles <span class="token punctuation">}</span> <span class="token keyword">from</span> <span class="token string">'@material-ui/core/styles'</span><span class="token punctuation">;</span>

<span class="token keyword">const</span> theme <span class="token operator">=</span> <span class="token function">createMuiTheme</span><span class="token punctuation">(</span><span class="token punctuation">)</span><span class="token punctuation">;</span>

<span class="token keyword">const</span> useStyles <span class="token operator">=</span> <span class="token function">makeStyles</span><span class="token punctuation">(</span><span class="token punctuation">(</span><span class="token parameter">theme</span><span class="token punctuation">)</span> <span class="token operator">=></span> <span class="token punctuation">{</span>
  <span class="token literal-property property">root</span><span class="token operator">:</span> <span class="token punctuation">{</span>
    <span class="token comment">// some CSS that accesses the theme</span>
  <span class="token punctuation">}</span>
<span class="token punctuation">}</span><span class="token punctuation">)</span><span class="token punctuation">;</span>

<span class="token keyword">function</span> <span class="token function">App</span><span class="token punctuation">(</span><span class="token punctuation">)</span> <span class="token punctuation">{</span>
  <span class="token keyword">const</span> classes <span class="token operator">=</span> <span class="token function">useStyles</span><span class="token punctuation">(</span><span class="token punctuation">)</span><span class="token punctuation">;</span> <span class="token comment">// ❌ If you have this, consider moving it</span>
  <span class="token comment">// inside of a component wrapped with &lt;ThemeProvider /></span>
  <span class="token keyword">return</span> <span class="token tag"><span class="token tag"><span class="token punctuation">&lt;</span><span class="token class-name">ThemeProvider</span></span> <span class="token attr-name">theme</span><span class="token script language-javascript"><span class="token script-punctuation punctuation">=</span><span class="token punctuation">{</span>theme<span class="token punctuation">}</span></span><span class="token punctuation">></span></span><span class="token punctuation">{</span>children<span class="token punctuation">}</span><span class="token tag"><span class="token tag"><span class="token punctuation">&lt;/</span><span class="token class-name">ThemeProvider</span></span><span class="token punctuation">></span></span><span class="token punctuation">;</span>
<span class="token punctuation">}</span>

Update MUI packages

Material UI v5 and @mui/styles

Install the Material UI v5 packages.

With npm:

<span class="token function">npm</span> <span class="token function">install</span> @mui/material @mui/styles

With yarn:

<span class="token function">yarn</span> <span class="token function">add</span> @mui/material @mui/styles

If you're using @material-ui/lab or @material-ui/icons, you will need to install the new packages.

@material-ui/lab

With npm:

<span class="token function">npm</span> <span class="token function">install</span> @mui/lab

With yarn:

<span class="token function">yarn</span> <span class="token function">add</span> @mui/lab

@material-ui/icons

With npm:

<span class="token function">npm</span> <span class="token function">install</span> @mui/icons-material

With yarn:

<span class="token function">yarn</span> <span class="token function">add</span> @mui/icons-material

Date and time pickers

The date and time picker components have been moved to MUI X. If you are using @material-ui/date-pickers or the pickers in the @mui/lab package, you will need to migrate to @mui/x-date-pickers. See Migration from the lab for details.

Peer dependencies

Next, add the Emotion packages.

With npm:

<span class="token function">npm</span> <span class="token function">install</span> @emotion/react @emotion/styled

With yarn:

<span class="token function">yarn</span> <span class="token function">add</span> @emotion/react @emotion/styled

styled-components (optional)

If you want to use Material UI v5 with styled-components instead of Emotion, check out the Material UI installation guide.

Note that if your app uses server-side rendering (SSR), there is a known bug with the Babel plugin for styled-components which prevents @mui/styled-engine-sc (the adapter for styled-components) from being used.

We strongly recommend using the default setup with Emotion instead.

Replace all imports

With the release of v5, the names of all related packages were changed from @material-ui/* to @mui/* as part of our updated branding. See this blog post for details.

Updated package names 
@material-ui/core -> @mui/material
@material-ui/unstyled -> @mui/base
@material-ui/icons -> @mui/icons-material
@material-ui/styles -> @mui/styles
@material-ui/system -> @mui/system
@material-ui/lab -> @mui/lab
@material-ui/types -> @mui/types
@material-ui/styled-engine -> @mui/styled-engine
@material-ui/styled-engine-sc ->@mui/styled-engine-sc
@material-ui/private-theming -> @mui/private-theming
@material-ui/codemod -> @mui/codemod
@material-ui/docs -> @mui/docs
@material-ui/envinfo -> @mui/envinfo

Remove old packages

Once you've installed all the necessary packages and ensured that your app still runs, you can safely remove the old @material-ui/* packages by running npm uninstall @material-ui/* or yarn remove @material-ui/*.

Fix CSS specificity (optional)

If you want to apply styles to components by importing a CSS file, you need to bump up the specificity to be able to target the correct components.

Consider the following example:

<span class="token keyword">import</span> <span class="token string">'./style.css'</span><span class="token punctuation">;</span>
<span class="token keyword">import</span> Chip <span class="token keyword">from</span> <span class="token string">'@mui/material/Chip'</span><span class="token punctuation">;</span>

<span class="token keyword">const</span> <span class="token function-variable function">ChipWithGreenIcon</span> <span class="token operator">=</span> <span class="token punctuation">(</span><span class="token punctuation">)</span> <span class="token operator">=></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">Chip</span></span>
    <span class="token attr-name">classes</span><span class="token script language-javascript"><span class="token script-punctuation punctuation">=</span><span class="token punctuation">{</span><span class="token punctuation">{</span> <span class="token literal-property property">deleteIcon</span><span class="token operator">:</span> <span class="token string">'green'</span> <span class="token punctuation">}</span><span class="token punctuation">}</span></span>
    <span class="token attr-name">label</span><span class="token attr-value"><span class="token punctuation attr-equals">=</span><span class="token punctuation">"</span>delete icon is green<span class="token punctuation">"</span></span>
    <span class="token attr-name">onDelete</span><span class="token script language-javascript"><span class="token script-punctuation punctuation">=</span><span class="token punctuation">{</span><span class="token punctuation">(</span><span class="token punctuation">)</span> <span class="token operator">=></span> <span class="token punctuation">{</span><span class="token punctuation">}</span><span class="token punctuation">}</span></span>
  <span class="token punctuation">/></span></span>
<span class="token punctuation">)</span><span class="token punctuation">;</span>

In this example, in order to correctly apply a particular style to the delete icon of Chip, one option is to increase the specificity of your CSS classes, as shown below:

<span class="token selector">.MuiChip-root .green</span> <span class="token punctuation">{</span>
  <span class="token property">color</span><span class="token punctuation">:</span> green<span class="token punctuation">;</span>
<span class="token punctuation">}</span>

By contrast, the following CSS snippet will not apply the style to the delete icon:

<span class="token selector">.green</span> <span class="token punctuation">{</span>
  <span class="token property">color</span><span class="token punctuation">:</span> green<span class="token punctuation">;</span>
<span class="token punctuation">}</span>

Run codemods

The following codemods will automatically adjust the bulk of your code to account for breaking changes in v5.

Make sure that your application still runs without errors after running each codemod, and commit the changes before continuing to the next step.

preset-safe

This codemod contains most of the transformers that are necessary for migration. It should be only applied once per folder.

npx @mui/codemod v5.0.0/preset-safe <span class="token operator">&lt;</span>path<span class="token operator">></span>

variant-prop

This codemod transforms the <TextField/>, <FormControl/>, and <Select/> components by applying variant="standard" if no variant is defined—the default variant has changed from "standard" in v4 to "outlined" in v5.

<span class="token comment">// ❌ if you have a theme setup like this, don't run this codemod.</span>
<span class="token comment">// these default props can be removed later because `outlined` is the default value in v5</span>
<span class="token function">createMuiTheme</span><span class="token punctuation">(</span><span class="token punctuation">{</span>
  <span class="token literal-property property">components</span><span class="token operator">:</span> <span class="token punctuation">{</span>
    <span class="token literal-property property">MuiTextField</span><span class="token operator">:</span> <span class="token punctuation">{</span>
      <span class="token literal-property property">defaultProps</span><span class="token operator">:</span> <span class="token punctuation">{</span>
        <span class="token literal-property property">variant</span><span class="token operator">:</span> <span class="token string">'outlined'</span><span class="token punctuation">,</span>
      <span class="token punctuation">}</span><span class="token punctuation">,</span>
    <span class="token punctuation">}</span><span class="token punctuation">,</span>
  <span class="token punctuation">}</span><span class="token punctuation">,</span>
<span class="token punctuation">}</span><span class="token punctuation">)</span><span class="token punctuation">;</span>

If you want to keep variant="standard" in your components, run this codemod or else configure the corresponding default theme props.

npx @mui/codemod v5.0.0/variant-prop <span class="token operator">&lt;</span>path<span class="token operator">></span>

For more details, check out the variant-prop codemod README.

This codemod transforms the <Link /> component by applying underline="hover" if there is no underline prop defined—the default underline has changed from "hover" in v4 to "always" in v5.

<span class="token comment">// if you have theme setup like this, ❌ don't run this codemod.</span>
<span class="token comment">// this default props can be removed later because `always` is the default value in v5</span>
<span class="token function">createMuiTheme</span><span class="token punctuation">(</span><span class="token punctuation">{</span>
  <span class="token literal-property property">components</span><span class="token operator">:</span> <span class="token punctuation">{</span>
    <span class="token literal-property property">MuiLink</span><span class="token operator">:</span> <span class="token punctuation">{</span>
      <span class="token literal-property property">defaultProps</span><span class="token operator">:</span> <span class="token punctuation">{</span>
        <span class="token literal-property property">underline</span><span class="token operator">:</span> <span class="token string">'always'</span><span class="token punctuation">,</span>
      <span class="token punctuation">}</span><span class="token punctuation">,</span>
    <span class="token punctuation">}</span><span class="token punctuation">,</span>
  <span class="token punctuation">}</span><span class="token punctuation">,</span>
<span class="token punctuation">}</span><span class="token punctuation">)</span><span class="token punctuation">;</span>

If you want to keep underline="hover", run this codemod or else configure the corresponding default theme props.

npx @mui/codemod v5.0.0/link-underline-hover <span class="token operator">&lt;</span>path<span class="token operator">></span>

For more details, check out the link-underline-hover codemod README.

Address breaking changes

The codemods handle many of the breaking changes, but others must be addressed manually.

Whether or not you choose to use the codemods, you are now ready to move on to the first of two breaking changes documents.