Skip to content
+

Migrating to v6

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

Start using the alpha release

In your package.json file, change the package version from latest to next.

package.json
-"@mui/material": "latest",
+"@mui/material": "next",

Optionally, if you are using one of these packages, you can also change their version to next:

  • @mui/icons-material
  • @mui/system
  • @mui/lab
  • @mui/material-nextjs
  • @mui/styled-engine-sc
  • @mui/utils

Using next ensures your project always uses the latest v6 alpha release. Alternatively, you can also target and fix it to a specific version, for example, 6.0.0-alpha.0.

Why you should migrate

Material UI v6's biggest highlight is the introduction of Pigment CSS, a next-gen zero-runtime CSS-in-JS library, as an opt-in styling engine. Using it will make your project compatible with React Server Components, as well as help reduce its bundle size due to styles being extracted at build time, avoiding client-side recalculation.

As a lesson learned from v5, this major release introduces minimal breaking changes. Namely, browser support updates, a Node.js version bump, and the removal of the UMD bundle. These updates reduced the Material UI package size by 2.5MB, 25% of the total size, and can be, for the most part, migrated automatically via codemods.

Aside from that, v6 also includes a few quality-of-life improvements regarding styling:

  • The CssVarsProvider API is now stable. That enables you to rely on CSS variables, allowing for more intricate and performant customization possibilities, along with improved overall developer experience.
  • Support for container queries within the theme.
  • A new theme utility for adding styles to specific color modes.

Supported browsers and Node versions

The targets of the default bundle have changed in v6.

The exact versions will be pinned on release from the browserslist query: "> 0.5%, last 2 versions, Firefox ESR, not dead, safari >= 15.4, iOS >= 15.4".

  • Node.js 18 (up from 12)
  • Chrome 109 (up from 90)
  • Edge 121 (up from 91)
  • Firefox 115 (up from 78)
  • Safari 15.4 in both macOS and iOS (up from 14 in macOS and 12.5 in iOS)
  • and more (see .browserslistrc (stable entry))

Removed support for IE 11

Support for IE 11－that is, the legacy bundle and all IE 11-related code－is completely removed. This decreases Material UI's bundle size and eases future development.

If you need to support IE 11, you can use v5's legacy bundle. However, note that it won't get updates or bug fixes.

Update React & TypeScript version

Update React

The minimum supported version of React is v17.0.0 (the same as v5). Use the snippet below to update your project (replace the <version> with the one you want):

npm install react@<version> react-dom@<version>

Update TypeScript

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

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

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

Breaking changes

UMD bundle was removed

To align with React 19's removal of UMD builds, Material UI has also removed its UMD bundle. This results in a reduction of the @mui/material package size by 2.5MB or 25% of the total package size.

Instead, using ESM-based CDNs such as esm.sh is recommended. For alternative installation methods, refer to the CDN documentation.

Chip

Previously, the Chip component lost focus when the escape button was pressed, which differed from how other button-like components work. This issue has been resolved, and the Chip now retains focus as expected.

If you want to keep the previous behavior, add a custom onKeyUp handler, as shown below:

import * as React from 'react';
import Chip from '@mui/material/Chip';

export default function ChipExample() {
  const chipRef = React.useRef(null);
  const keyUpHandler = (event) => {
    if (event.key === 'Escape' && chipRef.current) {
      chipRef.current.blur();
    }
  };
  return (
    <Chip
      label="Chip Outlined"
      variant="outlined"
      ref={chipRef}
      onKeyUp={keyUpHandler}
    />
  );
}

Loading Button

The children passed to the Loading Button component is now wrapped in a <span> tag to avoid issues when using tools to translate websites.

Grid v2 (Unstable_Grid)

The Grid v2 component was updated to match the API of the new PigmentGrid component, to allow interoperability between the two:

  • The previous size and offset props were replaced with the size and offset props
  • The spacing mechanism was reworked to use the gap CSS property.

This brings some breaking changes described in the following sections.

Size and offset props

Previously, the size and offset props were named corresponding to the theme's breakpoints. For the default theme this was:

  • Size: xs, sm, md, lg, xl
  • Offset: xsOffset, smOffset, mdOffset, lgOffset, xlOffset

In v6, these props are renamed to size and offset:

  <Grid
-   xs={12}
-   sm={6}
-   xsOffset={2}
-   smOffset={3}
+   size={{ xs: 12, sm: 6 }}
+   offset={{ xs: 2, sm: 3 }}
  />

Note that if the size or offset is the same for all breakpoints, you can use a single value:

- <Grid xs={6} xsOffset={2} >
+ <Grid size={6} offset={2} >

Besides that, the true value for the size prop was renamed to "grow":

- <Grid xs />
+ <Grid size="grow" />

Use this codemod to migrate your project to the new size and offset props:

npx @mui/codemod@next v6.0.0/grid-v2-props <path/to/folder>

If you have custom breakpoints, the change is the same:

- <Grid mobile={12} mobileOffset={2} desktop={6} desktopOffset={4} >
+ <Grid size={{ mobile: 12, desktop: 6 }} offset={{ mobile: 2, desktop: 4 }} >

Which you can cover with the same codemod by providing the custom breakpoints as an argument:

npx @mui/codemod@next v6.0.0/grid-v2-props <path/to/folder> --jscodeshit='--muiBreakpoints=mobile,desktop'

Removal of the disableEqualOverflow prop

Previously, the Grid overflowed its parent. In v6, this is fixed, with the Grid being contained inside its parent's padding:

Before and after of the Grid no longer overflowing its parent in v6.

This removes the need for the disableEqualOverflow prop:

- <Grid disableEqualOverflow />
+ <Grid />

Spacing is no longer considered inside the Grid item's box

Previously, Grid items included spacing in their boxes. In v6, this is fixed:

Before and after of the Grid items no longer including spacing in their box.

useMediaQuery

The following deprecated types were removed:

  • MuiMediaQueryList: use MediaQueryList (from lib.dom.d.ts) instead.
  • MuiMediaQueryListEvent: use MediaQueryListEvent (from lib.dom.d.ts) instead.
  • MuiMediaQueryListListener: use (event: MediaQueryListEvent) => void instead.

Stabilized APIs

CssVarsProvider and extendTheme

The CssVarsProvider and extendTheme APIs are now stable. If you already use them in v5, you can now drop the experimental prefix.

- import { experimental_extendTheme as extendTheme, Experimental_CssVarsProvider as CssVarsProvider } from '@mui/material/styles';
+ import { extendTheme, CssVarsProvider } from '@mui/material/styles';

Check out the CSS theme variables page to learn more about it.

Add styles for specific color modes

Material UI v6 introduces a new utility for adding styles to specific color modes called theme.applyStyles. It's designed to replace theme.palette.mode when applying light or dark styles.

 const MyComponent = styled('button')(({ theme }) => ({
   padding: '0.5rem 1rem',
   border: '1px solid,
-  borderColor: theme.palette.mode === 'dark' ? '#fff' : '#000',
+  borderColor: '#000',
+  ...theme.applyStyles('dark', {
+    borderColor: '#fff',
+  })
 }))

Use these codemods to migrate your project to theme.applyStyles:

npx @mui/codemod@next v6.0.0/styled <path/to/folder-or-file>
npx @mui/codemod@next v6.0.0/sx-prop <path/to/folder-or-file>
npx @mui/codemod@next v6.0.0/theme-v6 <path/to/theme-file>

Deprecations

Components props

The components and componentsProps props have been deprecated in favor of slots and slotProps, making the API surface of the components more consistent.

Check out the deprecations page to learn which component no longer has these props.

System props

System props, such as mt={*}, bgcolor={*}, and others, are deprecated in the Box, Typography, Link, Grid, and Stack components. Move all system props into the sx prop by using the codemod below:

npx @mui/codemod@next v6.0.0/system-props <path/to/folder>

Or do it manually like the example below:

- <Button mr={2}>...</Button>
+ <Button sx={{ mr: 2 }}>...</Button>

Theme component variants

Custom component variants defined in the theme are now merged with the theme style overrides, defined within the root slot of the component. Update the theme file using the codemod:

npx @mui/codemod@next v6.0.0/theme-v6 <path/to/theme>

Or do it manually like the example below:

 createTheme({
   components: {
     MuiButton: {
-      variants: [ ... ],
+      styleOverrides: {
+        root: {
+          variants: [ ... ]
+        }
+      }
     }
   }
 })

This reduces the API surface and lets you define variants in other slots of the component.

Pigment CSS integration (optional)