Migration to Grid v2

This guide explains how and why to migrate from Material UI Grid v1 to v2.

Why you should migrate

Grid v2 has several new feature and many improvements over the original:

• Grid v2 uses CSS variables which remove CSS specificity from class selectors. Now you can use sx prop on the Grid to control any style you'd like.
• All grids are considered items without specifying the item prop.
• The long-awaited offset feature gives you more flexibility for positioning.
• Nested grids now have no depth limitation.
• The disableEqualOverflow flag disables the horizontal scrollbar in smaller viewports.

With Material UI v4

The Grid v2 is introduced in Material UI v5, so you have to follow the Material UI migration guide first.

With Material UI v5

The migration is expected to be smooth since most of the APIs remains the same. However, there is one breaking change that we want to clarify:

The default implementation of the negative margin in Grid v2 is spread equally on all sides (same as the Grid in Material UI v4).

Import

-import Grid from '@mui/material/Grid';
+import Grid from '@mui/material/Unstable_Grid2';

Remove props

The item and zeroMinWidth props have been removed in Grid v2:

-<Grid item zeroMinWidth xs={6}>
+<Grid xs={6}>

Negative margins

If you want to apply the negative margins similar to the Grid v1, specify disableEqualOverflow: true on the grid container:

To apply to all grids, add the default props to the theme:

import { createTheme, ThemeProvider } from '@mui/material/styles';
import Grid from '@mui/material/Unstable_Grid2';

const theme = createTheme({
  components: {
    MuiGrid2: {
      defaultProps: {
        // all grids under this theme will apply
        // negative margin on the top and left sides.
        disableEqualOverflow: true,
      },
    },
  },
});

function Demo() {
  return (
    <ThemeProvider theme={theme}>
      <Grid container>...grids</Grid>
    </ThemeProvider>
  );
}

Documentation page

Check out Grid v2 docs for all the demos and code samples.