# How to Use the MUI Grid Component for Responsive Layouts

> Master the MUI Grid component for responsive layouts. Learn to leverage breakpoint props and theme spacing for flexible 12-column grids. Build adaptable UIs effortlessly.

- Repository: [MUI/material-ui](https://github.com/mui/material-ui)
- Tags: how-to-guide
- Published: 2026-02-26

---

**The MUI Grid component is a CSS-flexbox-based layout system that enables responsive 12-column grids through breakpoint-specific props like `xs`, `sm`, and `md`, automatically handling gutters via theme spacing multiplication.**

The MUI Grid component in the `mui/material-ui` repository provides a declarative way to build responsive layouts without writing custom media queries. Implemented in [`packages/mui-material/src/Grid/Grid.tsx`](https://github.com/mui/material-ui/blob/main/packages/mui-material/src/Grid/Grid.tsx), this component wraps the low-level `createGrid` factory from the system package to inject theme-aware breakpoints and spacing. By using the MUI Grid component for responsive layouts, you can control column widths, offsets, and direction changes across mobile, tablet, and desktop viewports with minimal code.

## Core Architecture and Implementation

The public Grid component is defined in **[`packages/mui-material/src/Grid/Grid.tsx`](https://github.com/mui/material-ui/blob/main/packages/mui-material/src/Grid/Grid.tsx)** as a thin wrapper around the `createGrid` utility from [`packages/mui-system/src/Grid/createGrid.ts`](https://github.com/mui/material-ui/blob/main/packages/mui-system/src/Grid/createGrid.ts). This architecture separates the styling logic from Material-UI specific defaults, allowing the component to resolve **ResponsiveStyleValue** types against the theme's breakpoint keys (`xs`, `sm`, `md`, `lg`, `xl`).

The component operates on two fundamental modes:

- **Container mode**: Activated by the `container` prop, which sets `display: flex` and establishes the grid context for child items.
- **Item mode**: The default state where the component receives `size`, `offset`, and spacing props to determine its flex-basis and margins within the container.

## Responsive Props and Breakpoint Behavior

Every layout prop on the MUI Grid component accepts a **ResponsiveStyleValue**, which can be a scalar value, an array, or an object keyed by breakpoint. The system resolves these values at runtime using the current theme breakpoints, enabling per-breakpoint control without media queries.

Key responsive props include:

- **`size`** (or specific breakpoint keys like `xs`, `sm`): Controls the flex-basis of an item. Accepts `auto`, `grow`, `number`, or `false`.
- **`offset`**: Adds a left margin equivalent to a column count. Use syntax like `mdOffset={1}` to offset specifically at the `md` breakpoint.
- **`direction`**: Maps to CSS `flex-direction`. Accepts responsive values like `{ xs: 'column', sm: 'row' }`.
- **`wrap`**: Maps to CSS `flex-wrap`. Accepts responsive values like `{ xs: 'nowrap', sm: 'wrap' }`.
- **`spacing`**, **`rowSpacing`**, **`columnSpacing`**: Multiplied by `theme.spacing` to generate gutters. These create negative margins on the container and matching paddings on items.

## Implementation Examples

### Basic 12-Column Responsive Layout

The most common pattern uses breakpoint-specific props to adjust column widths across viewports. In [`docs/data/material/components/grid/BasicGrid.tsx`](https://github.com/mui/material-ui/blob/main/docs/data/material/components/grid/BasicGrid.tsx), the component demonstrates how `xs={12}` occupies full width on mobile, while `sm={6}` and `md={4}` create halves and thirds on larger screens.

```tsx
import Grid from '@mui/material/Grid';
import Paper from '@mui/material/Paper';

export default function BasicGrid() {
  return (
    <Grid container spacing={2}>
      {/* Full width on xs, half width on sm, one-third on md+ */}
      <Grid item xs={12} sm={6} md={4}>
        <Paper>Item 1</Paper>
      </Grid>
      <Grid item xs={12} sm={6} md={4}>
        <Paper>Item 2</Paper>
      </Grid>
      <Grid item xs={12} sm={6} md={4}>
        <Paper>Item 3</Paper>
      </Grid>
    </Grid>
  );
}

```

The `spacing={2}` prop generates a 16px gutter (2 × 8px theme spacing unit), applied through negative margins on the container and compensating padding on items.

### Dynamic Direction and Wrapping

Change the flex axis and wrapping behavior at specific breakpoints by passing objects to the `direction` and `wrap` props.

```tsx
<Grid
  container
  spacing={2}
  direction={{ xs: 'column', sm: 'row' }}
  wrap={{ xs: 'nowrap', sm: 'wrap' }}
>
  <Grid item xs={12} sm={6}>
    <Paper>Content A</Paper>
  </Grid>
  <Grid item xs={12} sm={6}>
    <Paper>Content B</Paper>
  </Grid>
</Grid>

```

This configuration stacks items vertically on mobile (`column`) with no wrapping, then switches to horizontal layout (`row`) with normal wrapping on tablet and desktop viewports.

### Column Offsetting

Use the `offset` prop (or breakpoint-specific variants like `mdOffset`) to push items right by a specified number of columns, effectively creating empty space or centering content.

```tsx
<Grid container spacing={2}>
  <Grid item xs={12} sm={6} md={4} sx={{ margin: 'auto' }}>
    <Paper>Centered Card</Paper>
  </Grid>
  {/* Push one column to the right on md breakpoint */}
  <Grid item xs={12} md={4} mdOffset={1}>
    <Paper>Offset Card</Paper>
  </Grid>
</Grid>

```

The offset calculation is handled in the `GridBaseProps` definition within [`packages/mui-material/src/Grid/Grid.tsx`](https://github.com/mui/material-ui/blob/main/packages/mui-material/src/Grid/Grid.tsx), where it translates column counts into margin-left percentages.

### Nested Grid Containers

Grids can be nested infinitely. The `unstable_level` internal prop (documented in the source comments of [`Grid.tsx`](https://github.com/mui/material-ui/blob/main/Grid.tsx)) tracks nesting depth to calculate correct gutter collapse, preventing double-padding issues.

```tsx
<Grid container spacing={2}>
  <Grid item xs={12}>
    <Grid container spacing={1}>
      <Grid item xs={6}>
        <Paper>Nested 1</Paper>
      </Grid>
      <Grid item xs={6}>
        <Paper>Nested 2</Paper>
      </Grid>
    </Grid>
  </Grid>
</Grid>

```

Each nested container maintains its own spacing context, ensuring that the 16px outer gutters and 8px inner gutters do not compound incorrectly.

### Custom Breakpoints

Because the Grid reads breakpoint values from the theme, custom breakpoints defined in `createTheme` are automatically respected by all responsive props.

```tsx
const theme = createTheme({
  breakpoints: {
    values: {
      xs: 0,
      sm: 480,
      md: 768,
      lg: 1024,
      xl: 1440,
    },
  },
});

// In your component:
<Grid container spacing={2}>
  <Grid item xs={12} sm={6} md={3}>
    <Paper>Responsive</Paper>
  </Grid>
</Grid>

```

## Summary

- The MUI Grid component is implemented in [`packages/mui-material/src/Grid/Grid.tsx`](https://github.com/mui/material-ui/blob/main/packages/mui-material/src/Grid/Grid.tsx) and built on the `createGrid` factory from the system package.
- Use the `container` prop to establish a flex context, and the `item` prop (implicit or explicit) to define child behavior.
- All layout props accept **ResponsiveStyleValue** objects keyed by `xs`, `sm`, `md`, `lg`, or `xl` breakpoints.
- **Spacing** values are multiplied by `theme.spacing` to generate consistent gutters via negative margins and padding.
- **Offset** props (`xsOffset`, `mdOffset`, etc.) create left-margin gaps equivalent to column counts.
- The `unstable_level` internal tracking enables correct gutter behavior in **nested grids**.
- Reference implementations are available in [`docs/data/material/components/grid/BasicGrid.tsx`](https://github.com/mui/material-ui/blob/main/docs/data/material/components/grid/BasicGrid.tsx), [`ResponsiveGrid.tsx`](https://github.com/mui/material-ui/blob/main/ResponsiveGrid.tsx), [`NestedGrid.tsx`](https://github.com/mui/material-ui/blob/main/NestedGrid.tsx), and [`OffsetGrid.tsx`](https://github.com/mui/material-ui/blob/main/OffsetGrid.tsx).

## Frequently Asked Questions

### How does the MUI Grid spacing prop calculate gutter sizes?

The `spacing` prop accepts a number that is multiplied by the theme's spacing unit (default 8px). In [`packages/mui-material/src/Grid/Grid.tsx`](https://github.com/mui/material-ui/blob/main/packages/mui-material/src/Grid/Grid.tsx), the component generates negative margins on the container and matching paddings on items, creating gutters without affecting the outer layout boundaries. For example, `spacing={2}` produces 16px gutters.

### What is the difference between the container and item props in MUI Grid?

The `container` boolean prop activates flex container mode (`display: flex`), enabling the component to manage child Grid items. Without `container`, the component behaves as a flex item that receives sizing and offset props. A Grid can be both a container and an item simultaneously when both props are present, enabling complex nested layouts.

### Can I use custom breakpoints with the MUI Grid component?

Yes. The Grid component reads breakpoint definitions from the theme provided by `ThemeProvider`. When you customize breakpoints in `createTheme`, the Grid automatically recognizes these keys in responsive prop objects (e.g., `{ customBreakpoint: 6 }`). The component resolves these values using the same internal logic that handles standard `xs` through `xl` breakpoints.

### How do I center a column or offset it from the left?

Use the **`offset`** prop or its breakpoint-specific variants (`smOffset`, `mdOffset`, etc.) to add left margins equivalent to column counts. For true centering of an item with automatic margins, apply `sx={{ margin: 'auto' }}` to the Grid item, or use offset calculations to push the item from the left edge (e.g., `mdOffset={4}` to skip four columns on medium screens).