Grid

Grid acts as a generic container, wrapping around the elements to be arranged.

Introduction

The Grid component, based on a 12-column grid layout, creates visual consistency between layouts while allowing flexibility across a wide variety of designs.

Basics

import Grid from '@mui/joy/Grid';

Column widths are integer values between 1 and 12. They apply at any breakpoint and indicate how many columns are occupied by the component.

By default, the value given to a breakpoint is applied to all the other wider breakpoints.

For example, xs={12} sizes a component to occupy the whole viewport width regardless of its size, even if you do not pass any value for wider breakpoints like sm or md.

xs=8

xs=4

xs=8

<Grid container spacing={2} sx={{ flexGrow: 1 }}>
  <Grid xs={8}>
    <Item>xs=8</Item>
  </Grid>
  <Grid xs={4}>
    <Item>xs=4</Item>
  </Grid>
  <Grid xs={4}>
    <Item>xs=4</Item>
  </Grid>
  <Grid xs={8}>
    <Item>xs=8</Item>
  </Grid>
</Grid>

<Grid container spacing={2} sx={{ flexGrow: 1 }}>
  <Grid xs={8}>
    <Item>xs=8</Item>
  </Grid>
  <Grid xs={4}>
    <Item>xs=4</Item>
  </Grid>
  <Grid xs={4}>
    <Item>xs=4</Item>
  </Grid>
  <Grid xs={8}>
    <Item>xs=8</Item>
  </Grid>
</Grid>

Press Enter to start editing

Customization

Grid with multiple breakpoints

Components may have multiple widths defined, causing the layout to change at the defined breakpoint. Width values given to larger breakpoints override those given to smaller breakpoints.

For example, xs={12} sm={6} sizes a component to occupy half of the viewport width (6 columns) when viewport width is 600 or more pixels. For smaller viewports, the component fills all 12 available columns.

xs=6 md=8

xs=6 md=4

xs=6 md=8

<Grid container spacing={2} sx={{ flexGrow: 1 }}>
  <Grid xs={6} md={8}>
    <Item>xs=6 md=8</Item>
  </Grid>
  <Grid xs={6} md={4}>
    <Item>xs=6 md=4</Item>
  </Grid>
  <Grid xs={6} md={4}>
    <Item>xs=6 md=4</Item>
  </Grid>
  <Grid xs={6} md={8}>
    <Item>xs=6 md=8</Item>
  </Grid>
</Grid>

<Grid container spacing={2} sx={{ flexGrow: 1 }}>
  <Grid xs={6} md={8}>
    <Item>xs=6 md=8</Item>
  </Grid>
  <Grid xs={6} md={4}>
    <Item>xs=6 md=4</Item>
  </Grid>
  <Grid xs={6} md={4}>
    <Item>xs=6 md=4</Item>
  </Grid>
  <Grid xs={6} md={8}>
    <Item>xs=6 md=8</Item>
  </Grid>
</Grid>

Press Enter to start editing

Spacing

To control space between children, use the spacing prop. The spacing value can be any positive number, including decimals and any string. The prop is converted into a CSS property using the theme.spacing() helper.

Row & column spacing

The rowSpacing and columnSpacing props allow for specifying the row and column gaps independently. It's similar to the row-gap and column-gap properties of CSS Grid.

Responsive values

You can switch the props' value based on the active breakpoint.

xs=2

<Grid
  container
  spacing={{ xs: 2, md: 3 }}
  columns={{ xs: 4, sm: 8, md: 12 }}
  sx={{ flexGrow: 1 }}
>
  {Array.from(Array(6)).map((_, index) => (
    <Grid xs={2} sm={4} md={4} key={index}>
      <Item>xs=2</Item>
    </Grid>
  ))}
</Grid>

<Grid
  container
  spacing={{ xs: 2, md: 3 }}
  columns={{ xs: 4, sm: 8, md: 12 }}
  sx={{ flexGrow: 1 }}
>
  {Array.from(Array(6)).map((_, index) => (
    <Grid xs={2} sm={4} md={4} key={index}>
      <Item>xs=2</Item>
    </Grid>
  ))}
</Grid>

Press Enter to start editing

Responsive values is supported by:

columns
columnSpacing
direction
rowSpacing
spacing
all the other props of the system

⚠️ When using a responsive columns prop, each grid item needs its corresponding breakpoint. For instance, this is not working. The grid item misses the value for md:

<Grid container columns={{ xs: 4, md: 12 }}>
  <Grid xs={2} />
</Grid>

Auto-layout

The Auto-layout makes the grid items equitably share the available space. This also means that you can set the width of one grid item, and the others will automatically resize around it.

xs=6

<Grid container spacing={3} sx={{ flexGrow: 1 }}>
  <Grid xs>
    <Item>xs</Item>
  </Grid>
  <Grid xs={6}>
    <Item>xs=6</Item>
  </Grid>
  <Grid xs>
    <Item>xs</Item>
  </Grid>
</Grid>

<Grid container spacing={3} sx={{ flexGrow: 1 }}>
  <Grid xs>
    <Item>xs</Item>
  </Grid>
  <Grid xs={6}>
    <Item>xs=6</Item>
  </Grid>
  <Grid xs>
    <Item>xs</Item>
  </Grid>
</Grid>

Press Enter to start editing

Variable width content

Set one of the size breakpoint props to "auto" instead of true or a number to render a column based on the natural width of its content.

variable width content

xs=6

<Grid container spacing={3} sx={{ flexGrow: 1 }}>
  <Grid xs="auto">
    <Item>variable width content</Item>
  </Grid>
  <Grid xs={6}>
    <Item>xs=6</Item>
  </Grid>
  <Grid xs>
    <Item>xs</Item>
  </Grid>
</Grid>

<Grid container spacing={3} sx={{ flexGrow: 1 }}>
  <Grid xs="auto">
    <Item>variable width content</Item>
  </Grid>
  <Grid xs={6}>
    <Item>xs=6</Item>
  </Grid>
  <Grid xs>
    <Item>xs</Item>
  </Grid>
</Grid>

Press Enter to start editing

Columns

You can change the default number of columns (12) with the columns prop.

xs=8

<Grid container spacing={2} columns={16} sx={{ flexGrow: 1 }}>
  <Grid xs={8}>
    <Item>xs=8</Item>
  </Grid>
  <Grid xs={8}>
    <Item>xs=8</Item>
  </Grid>
</Grid>

<Grid container spacing={2} columns={16} sx={{ flexGrow: 1 }}>
  <Grid xs={8}>
    <Item>xs=8</Item>
  </Grid>
  <Grid xs={8}>
    <Item>xs=8</Item>
  </Grid>
</Grid>

Press Enter to start editing

System props

As a CSS utility component, Grid supports all MUI System properties. You can use them as props directly on the component. For instance, a margin-top:

<Grid mt={2}>

Interactive demo

Below is an interactive demo that lets you explore the visual results of the different settings:

Cell 1

Cell 2

Cell 3

<Grid
  container
  direction="row"
  justifyContent="center"
  alignItems="center"
>

Limitations

Negative margin

The spacing between items is implemented with a negative margin. This might lead to unexpected behaviors. For instance, to apply a background color, you need to apply display: flex; to the parent.

direction: column | column-reverse

The xs, sm, md, lg, and xl props are not supported within direction="column" and direction="column-reverse" containers.

They define the number of grids the component will use for a given breakpoint. They are intended to control width using flex-basis in row containers but they will impact height in column containers. If used, these props may have undesirable effects on the height of the Grid item elements.

CSS Grid Layout

The Grid component is using CSS flexbox internally. But as seen below, you can easily use the system and CSS Grid to layout your pages.

xs=8

xs=4

xs=8

<Box display="grid" gridTemplateColumns="repeat(12, 1fr)" gap={2}>
  <Box gridColumn="span 8">
    <Item>xs=8</Item>
  </Box>
  <Box gridColumn="span 4">
    <Item>xs=4</Item>
  </Box>
  <Box gridColumn="span 4">
    <Item>xs=4</Item>
  </Box>
  <Box gridColumn="span 8">
    <Item>xs=8</Item>
  </Box>
</Box>

<Box display="grid" gridTemplateColumns="repeat(12, 1fr)" gap={2}>
  <Box gridColumn="span 8">
    <Item>xs=8</Item>
  </Box>
  <Box gridColumn="span 4">
    <Item>xs=4</Item>
  </Box>
  <Box gridColumn="span 4">
    <Item>xs=4</Item>
  </Box>
  <Box gridColumn="span 8">
    <Item>xs=8</Item>
  </Box>
</Box>

Press Enter to start editing

Common examples

Centering children

To center a grid item's content, specify display="flex" directly on the item. Then use justifyContent and/or alignItems to adjust the position of the content, as shown below:

Jimmy

Michal

Jun

Marija

Anatomy

The Grid component is composed of a single root <div> element:

<div class="JoyGrid-root">
  <!-- Grid contents -->
</div>