Upgrade to v7

If you are using the deprecated grid and wish to upgrade, run the following codemod:

npx @mui/codemod v7.0.0/grid-props <path/to/folder>

See the Grid upgrade guide for more information.

If you are using the deprecated grid and wish to continue using it, update the Grid references as follows:

 // imports
-import Grid, { gridClasses, GridProps } from '@mui/material/Grid';
+import Grid, { gridLegacyClasses, GridLegacyProps } from '@mui/material/GridLegacy';
-import { Grid } from '@mui/material';
+import { GridLegacy as Grid } from '@mui/material';
 // theme
 const theme = createTheme({
   components: {
-    MuiGrid: {
+    MuiGridLegacy: {
       // ...
 // CSS classes
-.MuiGrid-root
+.MuiGridLegacy-root

If you are using Grid2, update the Grid2 references as follows:

 // imports
-import Grid, { grid2Classes as gridClasses, Grid2Props as GridProps } from '@mui/material/Grid2';
+import Grid, { gridClasses, GridProps } from '@mui/material/Grid';
-import { Grid2 as Grid } from '@mui/material';
+import { Grid } from '@mui/material';
 // theme
 const theme = createTheme({
   components: {
-    MuiGrid2: {
+    MuiGrid: {
       // ...
 // CSS classes
-.MuiGrid2-root
+.MuiGrid-root

InputLabel size prop standardized

The size prop for InputLabel now follows the standard naming convention used across other components like Button and TextField . 'normal' has been replaced with 'medium' for consistency.

If you were using size="normal" , update it to size="medium" :

-<InputLabel size="normal">Label</InputLabel>
+<InputLabel size="medium">Label</InputLabel>

The default behavior remains unchanged, so no updates are needed unless you explicitly set size="normal" .

Use this codemod to automatically update the size value:

npx @mui/codemod v7.0.0/input-label-size-normal-medium <path/to/folder>

Note: Because the default size of InputLabel was changed from normal to medium , the class MuiInputLabel‑sizeMedium is no longer added. If you relied on this class for custom styling, use a different class.

SvgIcon's data-testid removed

The default data-testid prop has been removed from the icons in @mui/icons-material in production bundles. This change ensures that the data-testid prop is only defined where needed, reducing the potential for naming clashes and removing unnecessary properties in production.

TablePaginationActions types import path changed

The import path for the types has changed from @mui/material/TablePagination/TablePaginationActions to @mui/material/TablePaginationActions .

- import type { TablePaginationActionsProps } from '@mui/material/TablePagination/TablePaginationActions';
+ import type { TablePaginationActionsProps } from '@mui/material/TablePaginationActions';

Theme behavior changes

When CSS theme variables is enabled with built-in light and dark color schemes, the theme no longer changes between modes. The snippet below demonstrates this behavior when users toggle the dark mode, the mode state from useColorScheme changes, but the theme object no longer changes:

import {
  ThemeProvider,
  createTheme,
  useTheme,
  useColorScheme,
} from '@mui/material/styles';
const theme = createTheme({




    

  cssVariables: {
    colorSchemeSelector: 'class',
  colorSchemes: {
    light: true,
    dark: true,
});
console.log(theme.palette.mode); // 'light' is the default mode
function ColorModeToggle() {
  const { setMode, mode } = useColorScheme();
  const theme = useTheme();
  React.useEffect(() => {
    console.log(mode); // logged 'light' at first render, and 'dark' after the button click
  }, [mode]);
  React.useEffect(() => {
    // logged 'light' at first render, no log after the button click
    console.log(theme.palette.mode);
  }, [theme]);
  return <button onClick={() => setMode('dark')}>Toggle dark mode</button>;
function App() {
  return (
    <ThemeProvider theme={theme}>
      <ColorModeToggle />
    </ThemeProvider>

This default behavior was made to improve performance by avoiding unnecessary re-renders when the mode changes.

It's recommended to use the theme.vars.* as values in your styles to refer to the CSS variables directly:

const Custom = styled('div')(({ theme }) => ({
  color: theme.vars.palette.text.primary,
  background: theme.vars.palette.primary.main,
}));

If you need to do runtime calculations, we recommend using CSS instead of JavaScript whenever possible. For example, adjusting the alpha channel of a color can be done using the color-mix function :

const Custom = styled('div')(({ theme }) => ({
  color: `color-mix(in srgb, ${theme.vars.palette.text.primary}, transparent 50%)`,
}));

However, if CSS approach is not possible, you can access the value directly from the theme.colorSchemes object, then apply both light and dark styles:

const Custom = styled('div')(({ theme }) => ({
  color: alpha(theme.colorSchemes.light.palette.text.primary, 0.5),
  ...theme.applyStyles('dark', {
    color: alpha(theme.colorSchemes.dark.palette.text.primary, 0.5),
  }),
}));

If any of the methods above do not suit your project, you can opt out from this behavior by passing the forceThemeRerender prop to the ThemeProvider component:

<ThemeProvider forceThemeRerender />

Deprecated APIs removed

APIs that were deprecated in v5 have been removed in v7.

createMuiTheme function

The deprecated createMuiTheme function has been removed. Use createTheme instead.

-import { createMuiTheme } from '@mui/material/styles';
+import { createTheme } from '@mui/material/styles';

Dialog's onBackdropClick prop

The deprecated onBackdropClick prop has been removed from the Dialog component. Please use the onClose callback instead, which receives the event and the reason for the dialog closing. Here's an example of how to use it:

function Example() {
  const [open, setOpen] = React.useState(




    
false);
  const handleClose = (event, reason) => {
    if (reason === 'backdropClick') {
      // Handle the backdrop click
    setOpen(false);
  return (
    <Dialog open={open} onClose={handleClose}>
      {/* Dialog content */}
    </Dialog>

experimentalStyled function

The deprecated experimentalStyled function has been removed. Use styled instead.

-import { experimentalStyled as styled } from '@mui/material/styles';
+import { styled } from '@mui/material/styles';

Hidden and PigmentHidden components

The deprecated Hidden and PigmentHidden components have been removed.

Use the sx prop to replace implementation="css" :

-<Hidden implementation="css" xlUp><Paper /></Hidden>
+<Paper sx={{ display: { xl: 'none', xs: 'block' } }} />

-<Hidden implementation="css" mdDown><Paper /></Hidden>
+<Paper sx={{ display: { xs: 'none', md: 'block' } }} />

Use the useMediaQuery hook to replace implementation="js" :

-<Hidden implementation="js" xlUp><Paper /></Hidden>
+const hidden = useMediaQuery(theme => theme.breakpoints.up('xl'));
+return hidden ? null : <Paper />;

Modal's onBackdropClick prop

The deprecated onBackdropClick prop has been removed from the Modal component. Please use the onClose callback instead, which receives the event and the reason for the modal closing. Here's an example of how to use it:

function Example() {
  const [open, setOpen] = React.useState(false);
  const handleClose = (event, reason) => {
    if (reason === 'backdropClick') {
      // Handle the backdrop click
    setOpen(false);
  return (
    <Modal open={open} onClose={handleClose}>
      {/* Modal content */}
    </Modal>

Rating's MuiRating-readOnly CSS class

The deprecated MuiRating-readOnly class was removed in favor of Mui-readOnly global class.

-.MuiRating-readOnly
+.Mui-readOnly

StepButtonIcon type

The deprecated StepButtonIcon type has been removed. Use StepButtonProps['icon'] instead.

-import { StepButtonIcon } from '@mui/material/StepButton';
+import { StepButtonProps } from '@mui/material/StepButton';
-StepButtonIcon
+StepButtonProps['icon']

StyledEngineProvider import path

Importing StyledEngineProvider from '@mui/material' was deprecated and now has been removed. Import it from '@mui/material/styles' instead:

-import { StyledEngineProvider } from '@mui/material';
+import { StyledEngineProvider } from '@mui/material/styles';

Lab components moved to the main package

The following @mui/lab components and hook have been moved to @mui/material :