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

ver.1
Top and left

ver.2
All sides

The overflow represents the negative margin of the grid.

Import

<span class="token deleted-sign deleted"><span class="token prefix deleted">-</span><span class="token line"> import Grid from '@mui/material/Grid';
</span></span><span class="token inserted-sign inserted"><span class="token prefix inserted">+</span><span class="token line"> import Grid from '@mui/material/Unstable_Grid2';</span></span>

Remove props

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

<span class="token deleted-sign deleted"><span class="token prefix deleted">-</span><span class="token line"> &lt;Grid item zeroMinWidth xs={6}>
</span></span><span class="token inserted-sign inserted"><span class="token prefix inserted">+</span><span class="token line"> &lt;Grid xs={6}></span></span>

Negative margins

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

ver.2
Top and left overflow

The overflow represents the negative margin of the grid.

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

<span class="token keyword">import</span> <span class="token punctuation">{</span> createTheme<span class="token punctuation">,</span> ThemeProvider <span class="token punctuation">}</span> <span class="token keyword">from</span> <span class="token string">'@mui/material/styles'</span><span class="token punctuation">;</span>
<span class="token keyword">import</span> Grid <span class="token keyword">from</span> <span class="token string">'@mui/material/Unstable_Grid2'</span><span class="token punctuation">;</span>

<span class="token keyword">const</span> theme <span class="token operator">=</span> <span class="token function">createTheme</span><span class="token punctuation">(</span><span class="token punctuation">{</span>
  <span class="token literal-property property">components</span><span class="token operator">:</span> <span class="token punctuation">{</span>
    <span class="token literal-property property">MuiGrid2</span><span class="token operator">:</span> <span class="token punctuation">{</span>
      <span class="token literal-property property">defaultProps</span><span class="token operator">:</span> <span class="token punctuation">{</span>
        <span class="token comment">// all grids under this theme will apply</span>
        <span class="token comment">// negative margin on the top and left sides.</span>
        <span class="token literal-property property">disableEqualOverflow</span><span class="token operator">:</span> <span class="token boolean">true</span><span class="token punctuation">,</span>
      <span class="token punctuation">}</span><span class="token punctuation">,</span>
    <span class="token punctuation">}</span><span class="token punctuation">,</span>
  <span class="token punctuation">}</span><span class="token punctuation">,</span>
<span class="token punctuation">}</span><span class="token punctuation">)</span><span class="token punctuation">;</span>

<span class="token keyword">function</span> <span class="token function">Demo</span><span class="token punctuation">(</span><span class="token punctuation">)</span> <span class="token punctuation">{</span>
  <span class="token keyword">return</span> <span class="token punctuation">(</span>
    <span class="token tag"><span class="token tag"><span class="token punctuation">&lt;</span><span class="token class-name">ThemeProvider</span></span> <span class="token attr-name">theme</span><span class="token script language-javascript"><span class="token script-punctuation punctuation">=</span><span class="token punctuation">{</span>theme<span class="token punctuation">}</span></span><span class="token punctuation">></span></span>
      <span class="token tag"><span class="token tag"><span class="token punctuation">&lt;</span><span class="token class-name">Grid</span></span> <span class="token attr-name">container</span><span class="token punctuation">></span></span><span class="token operator">...</span>grids<span class="token tag"><span class="token tag"><span class="token punctuation">&lt;/</span><span class="token class-name">Grid</span></span><span class="token punctuation">></span></span>
    <span class="token tag"><span class="token tag"><span class="token punctuation">&lt;/</span><span class="token class-name">ThemeProvider</span></span><span class="token punctuation">></span></span>
  <span class="token punctuation">)</span><span class="token punctuation">;</span>
<span class="token punctuation">}</span>

Documentation page

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