The Ultimate Guide to Material-UI Grid Containers and Items (MUI v5)

The Material-UI Grid is unusual in the universe of MUI components: a Grid is composed of individual children Grids with either a container or item layout prop enabled. The container and item props affect how the child Grids render in the DOM and determine which additional props are available for use.

I will show what happens in the DOM when either the container prop or item prop is enabled. I will also enable every prop available on a composing container Grid and on a composing item Grid and discuss the effects.

Finally we’ll see how to style the Grid with background color, margin, padding, width, height, and more. Related to this, here is a complete guide to aligning items in Material-UI Grid.

I have a Code Sandbox link with a live demo and full React code in the Resources section. Here’s a YouTube version of this post.

How to Use Material-UI Grid Containers

I forked the simple multi-breakpoint Grid example from the docs and set every documented prop on the wrapping container Grid. The off-centered padding is no mistake: this is how the Grid is designed.

Material-UI Grid Container with Props
Material-UI Grid Container

I added background color to show the padding and margin of the interior item Grids. Notice how only the top and left have padding. We will explore why this happens, and I will fix this by styling the container Grid using the sx prop.

Here’s the code for the simple Grid above:

<Grid
  container
  //spacing={2}
  rowSpacing={2}
  columnSpacing={2}
  columns={16}
  sx={gridStyles}
>
  <Grid item xs={6} md={10}>
    <Contents>xs=6 md=10</Contents>
  </Grid>
  <Grid item xs={10} md={6}>
    <Contents>xs=10 md=6</Contents>
  </Grid>
  <Grid item xs={10} md={6}>
    <Contents>xs=10 md=6</Contents>
  </Grid>
  <Grid item xs={6} md={10}>
    <Contents>xs=6 md=10</Contents>
  </Grid>
</Grid>

The wrapping Grid has container prop and the interior Grids have item prop. The Item component nested at the deepest levels is simply a Paper with some custom styling.

First, let’s examine the DOM effects of the props applied to the container Grid:

MUI Grid DOM
Material-UI Grid DOM

The first interesting thing I see is that there is a MuiGrid-container class applied but it is not directly affecting the DOM. The second interesting thing I noticed after playing with the spacing (or columnSpacing) is that the width adjusts by 100% + px when spacing is added.

Going through the props one-by-one, here’s the effects I see:

  • spacing – this adds padding-top and padding-left equally to each child Grid inside the container. It’s interesting that it doesn’t add padding-right or padding-bottom. If you want to have your grid look symmetrical in a larger UI context, you need to manually adding padding-right and padding-bottom at the containing Grid level.
Material-UI Grid Item prop in the DOM
Material-UI Grid Item prop in the DOM
  • rowSpacing – this adds padding-top to the Grid items
  • columnSpacing – this adds padding-left to the Grid items
  • columns – this changes the total column count from the default of 12. In my Grid example, I have a count of 16. Make sure that your child items add up to the column value for each breakpoint (i.e. in my example two children in one row need their xs values to total 16)
  • Read my guide on aligning Grid items with direction, justifyContent, or alignItems. I previously covered these extensively and did not use these props in the current example.

As a reminder, the Grid with container prop enabled should not be confused with the Container component. The Container component is used for horizontal layout (although the new MUI v5 Stack component is even better for horizontal layout!), while the Grid is used for two-dimensional layouts (in other words, layouts with both vertical and horizontal aspects).

How to Use Material-UI Grid Items

Material-UI Grids with the item prop enabled are deeply tied to the Grid container they are nested in. If you skipped the Grid container section, I recommend you take a look at the DOM screenshot I got of Grid item padding being manipulated by rowSpacing and columnSpacing props at the container level. I will refer to it below to explain the effects of props at the Grid item level.

I enabled all documented props applicable to the Grid item level and these were the effects:

  • xs and md multi-breakpoints – just like the MUI docs example I forked from, I left xs and md breakpoints. However, since I changed the Grid container-level columns prop to 16, my xs and md breakpoints needed to sum to 16 for each row.
    • Notice in the DOM screenshot above that the flex-basis and max-width are 37.5%. This is how the sx breakpoint is working: it is allocating 6/16 columns, or 6/16 % of the available width, to the highlighted Grid item div.
  • zeroMinWidth and wrap – these can be used together to create desired behavior for text that is larger than the Grid item. A common example is using ellipsis when text is too long.
  • sx – this is one of two new MUI v5 styling APIs. You can add any CSS styling via the sx prop, plus any MUI system values (i.e. bgcolor: 'background.paper'). Important: do not try to add margin to the Grid at the item level. It will affect the column calculations and cause unintended layout behavior.

A Grid with the item and a Grid with the container prop actually are quite similar. Both have similar style properties applied by the .MuiGrid-root class. The main purpose of the .MuiGrid-item class is to facilitate nested selecting and applying of styling such as the padding-left applied by the columnSpacing prop.

Styling the Material-UI Grid With the sx Prop

Let’s fix the strange padding on our Grid and make it look like something respectable:

Material-UI Grid with padding and margin
MUI Grid with padding and margin

To create this even styling, I passed the following style object to the Grid container sx prop:

const gridStyles = {
  backgroundColor: "blue",
  paddingBottom: 2,
  paddingRight: 2,
  marginTop: 2,
  marginLeft: "auto",
  marginRight: "auto",
  maxWidth: 500
};
  • Background color – this adds background color to the Grid container that ‘shows through’ the padding on the container and the padding on the item level Grids.
  • padding – The padding right and padding bottom are drawing on the MUI system values, not px values. In reality this is applying a value of 16px to both.
  • margin – The Grid margin is external to the blue background. I am using it to horizontally center the Grid and space it away from the top of the viewport.

Styling the Material-UI Grid with makeStyles Migrated to MUI v5

The code for styling the root of the Grid is almost identical between makeStyles and the sx prop. Simply put, the makeStyles hook is more verbose code to accomplish the same effect. I strongly recommend using the sx prop or the styles() API for new development.

The primary change for makeStyles from MUI v4 to v5 is the import. Now we use import { makeStyles } from "@mui/styles";.

//MUI v5 makeStyles hook

import { makeStyles } from "@mui/styles";

const useStyles = makeStyles({
  root: {
    backgroundColor: "blue",
    paddingBottom: 16,
    paddingRight: 16,
    marginTop: 16,
    marginLeft: "auto",
    marginRight: "auto",
    maxWidth: 500
  }
});

export default function FullWidthGrid() {
  const classes = useStyles();
  return (
    <>
      <Grid
        container
        className={classes.root}
    //Additional JSX
      </Grid>
  );
}

Resources

Read about the difference between MUI Grid, Bootstrap, flexbox, and CSS Grid here.

Here’s how to set MUI Grid item height.

Are you looking for training in Material-UI? Check out my review of the 3 best Material-UI courses in Udemy, including my top pick with 40+ hours of training content.

Code Sandbox link

MUI Grid Docs

MUI Grid API

Share this post:

Leave a Comment

This site uses Akismet to reduce spam. Learn how your comment data is processed.