Upgrade to Grid2

This guide explains how and why to migrate from the Grid component to the Grid2 component.

Grid component versions

In Material UI v7, the legacy Grid component has been deprecated and replaced by Grid2, which offers several new features as well as significant improvements to the developer experience. This guide explains how to upgrade from Grid to Grid2, and includes details for Material UI v5, v6, and v7.

Why you should upgrade

Grid2 provides the following improvements over the legacy Grid:

• It uses CSS variables, removing CSS specificity from class selectors. You can use sx prop on Grid2 to control any style you'd like.
• All grids are considered items without specifying the item prop.
• The offset feature gives you more flexibility for positioning.
• Nested grids now have no depth limitation.
• Its implementation doesn't use negative margins so it doesn't overflow like the legacy Grid.

How to upgrade

Prerequisites

Before proceeding with this upgrade:

• You must be on Material UI v5+.
• If you're in the process of upgrading your Material UI version, you should complete that upgrade first.

1. Update the import

Depending on the Material UI version you are using, you must update the import as follows:

2. Remove legacy props

The item and zeroMinWidth props have been removed in the updated Grid. You can safely remove them:

-<Grid item zeroMinWidth>
+<Grid>

3. Update the size props

In the legacy Grid, the size props were named to correspond with the theme's breakpoints. For the default theme, these were xs, sm, md, lg, and xl.

Starting from Material UI v6, these props are renamed to size on the updated Grid:

 <Grid
-  xs={12}
-  sm={6}
+  size={{ xs: 12, sm: 6 }}
 >

If the size is the same for all breakpoints, then you can use a single value:

-<Grid xs={6}>
+<Grid size={6}>

Additionally, the true value for the size props was renamed to "grow":

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

You can use the following codemod to update the size props:

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

4. Opt in to legacy negative margins

If you're using Material UI v5 and want to apply the negative margins similar to the legacy Grid, 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>
  );
}

Common issues

Column direction

Using direction="column" or direction="column-reverse" is not supported on the legacy Grid nor on the updated Grid2. If your layout used the legacy Grid with these values, it might break when you switch to the updated Grid. If you need a vertical layout, follow the instructions in the Grid2 documentation.

Documentation pages

• Grid2:
  • Documentation
  • API
• Legacy Grid:
  • Documentation
  • API