Migrating to v5: getting started

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

Material UI v5 migration

Getting started 👈 you are here
Breaking changes part one: style and theme
Breaking changes part two: components
Migrating from JSS
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 (for example 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.

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:

import { ThemeProvider, createMuiTheme, makeStyles } from '@material-ui/core/styles';

const theme = createMuiTheme();

const useStyles = makeStyles((theme) => {
  root: {
    // some CSS that accesses the theme
  }
});

function App() {
  const classes = useStyles(); // ❌ If you have this, consider moving it
  // inside of a component wrapped with <ThemeProvider />
  return <ThemeProvider theme={theme}>{children}</ThemeProvider>;
}

Update Material UI packages

Material UI v5 and `@mui/styles`

Install the Material UI v5 packages.

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

`@material-ui/lab`

`@material-ui/icons`

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.

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:

import './style.css';
import Chip from '@mui/material/Chip';

const ChipWithGreenIcon = () => (
  <Chip
    classes={{ deleteIcon: 'green' }}
    label="delete icon is green"
    onDelete={() => {}}
  />
);

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:

.MuiChip-root .green {
  color: green;
}

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

.green {
  color: green;
}

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@latest v5.0.0/preset-safe <path>

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.

// ❌ if you have a theme setup like this, don't run this codemod.
// these default props can be removed later because `outlined` is the default value in v5
createMuiTheme({
  components: {
    MuiTextField: {
      defaultProps: {
        variant: 'outlined',
      },
    },
  },
});

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

npx @mui/codemod@latest v5.0.0/variant-prop <path>

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

link-underline-hover

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.

// if you have theme setup like this, ❌ don't run this codemod.
// this default props can be removed later because `always` is the default value in v5
createMuiTheme({
  components: {
    MuiLink: {
      defaultProps: {
        underline: 'always',
      },
    },
  },
});

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

npx @mui/codemod@latest v5.0.0/link-underline-hover <path>

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.