Migrating to v5

Introduction

This document is a reference for upgrading your site 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.

Need to refer back to an older version of the docs? Check out the v4 documentation here.

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.

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)

Material UI no longer supports IE 11. If you need to support IE 11, check out the 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.

npm install @material-ui/core@^4.11.2 react@^17.0.0 react-dom@^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 will want to migrate from JSS to Emotion, but in the meantime you can continue to use the older JSS-based utilities with the deprecated @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:

npm install @mui/material @mui/styles

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

npm install @mui/lab @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.

Peer dependencies

Next, add the Emotion packages:

npm install @emotion/react @emotion/styled

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. 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

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/core @material-ui/icons @material-ui/lab

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.

You should not use this codemod if you have already defined variant: "outlined" as the default in the theme.

If you want to keep variant="standard" in your components, run this codemod:

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

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.

You should not use this codemod if you have already defined underline: "always" as the default in the theme.

If you want to keep underline="hover", run this codemod:

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

Major breaking changes

Core components

Every component forwards their ref. This is implemented by using React.forwardRef(). This affects the internal component tree and display name.
The innerRef prop has been removed. Use the ref prop instead.

Button

The button color prop is now “primary” by default, and “default” has been removed.
The variant="text" prop no longer has reduced padding.
The button now has a medium size by default instead of large.

-<Button variant="text" />
+<Button variant="text" size="large" />

Chip

The Chip color prop now defaults to “default” instead of “primary”.
The onDelete prop now receives the event as the first parameter.

TextField

The TextField variant now defaults to “outlined” instead of “standard”.
Rename rowsMax prop to maxRows:

-<TextField rowsMax={4} />
+<TextField maxRows={4} />

Select

The Select variant now defaults to “outlined” instead of “standard”.
Remove labelWidth prop. Use label instead:

-<Select labelWidth={20} />
+<Select label="Age" />

FormControl

The FormControl variant now defaults to “outlined” instead of “standard”.

Grid

The justify prop has been renamed to justifyContent:

-<Grid justify="center" />
+<Grid justifyContent="center" />

Hidden

The Hidden component has been removed. Use the sx prop with display instead:

-<Hidden smDown>
-  <Button>Hidden on small screens</Button>
-</Hidden>
+<Button sx={{ display: { xs: 'none', md: 'block' } }}>
+  Hidden on small screens
+</Button>

Theme

The theme.palette.type has been renamed to theme.palette.mode:

 createTheme({
   palette: {
-    type: 'dark',
+    mode: 'dark',
   },
 });

The theme.spacing() function now returns strings instead of numbers:

-paddingTop: theme.spacing(2), // 16
+paddingTop: theme.spacing(2), // '16px'

Styling

Material UI v5 uses Emotion as the default styling solution. If you want to continue using JSS (for example with makeStyles), install @mui/styles:

npm install @mui/styles

The @global key has been removed. Use the GlobalStyles component instead:

-const useStyles = makeStyles((theme) => ({
-  '@global': {
-    body: {
-      backgroundColor: theme.palette.background.default,
-    },
-  },
-}));
+import { GlobalStyles } from '@mui/material';
+
+<GlobalStyles styles={(theme) => ({
+  body: {
+    backgroundColor: theme.palette.background.default,
+  },
+})} />

Next steps

After completing the migration to v5, you can:

Migrate from JSS to Emotion for better performance
Update to React 18 for concurrent features
Explore new v5 features like the sx prop
Consider using CSS Variables for theming

Community

Migration

Introduction

Why you should migrate

Supported browsers and Node versions

Update React & TypeScript version

Update React

Update TypeScript

Set up ThemeProvider

Update Material UI packages

Material UI v5 and @mui/styles

Date and time pickers

Peer dependencies

Replace all imports

Remove old packages

Run codemods

preset-safe

variant-prop

link-underline-hover

Major breaking changes

Core components

Button

Chip

TextField

Select

FormControl

Grid

Hidden

Theme

Styling

Next steps

Build docs developers (and LLMs) love

Community

Migration

​Introduction

​Why you should migrate

​Supported browsers and Node versions

​Update React & TypeScript version

​Update React

​Update TypeScript

​Set up ThemeProvider

​Update Material UI packages

​Material UI v5 and @mui/styles

​Date and time pickers

​Peer dependencies

​Replace all imports

​Remove old packages

​Run codemods

​preset-safe

​variant-prop

​link-underline-hover

​Major breaking changes

​Core components

​Button

​Chip

​TextField

​Select

​FormControl

​Grid

​Hidden

​Theme

​Styling

​Next steps

Build docs developers (and LLMs) love

Introduction

Why you should migrate

Supported browsers and Node versions

Update React & TypeScript version

Update React

Update TypeScript

Set up ThemeProvider

Update Material UI packages

Material UI v5 and @mui/styles

Date and time pickers

Peer dependencies

Replace all imports

Remove old packages

Run codemods

preset-safe

variant-prop

link-underline-hover

Major breaking changes

Core components

Button

Chip

TextField

Select

FormControl

Grid

Hidden

Theme

Styling

Next steps