SINGULARITY
DOCS
Reference
Grid
The responsive layout grid adjusts to varying screen sizes and orientations, promoting uniformity across different layouts.
The
Grid component is ideal for layouts with a fixed number of columns. It allows multiple breakpoints to define the column span for each child element.How it works
The grid system is built with the
Grid component:- It employs CSS Flexbox (instead of CSS Grid) for enhanced adaptability.
- The grid is inherently a flex item. Apply the
containerprop to create a flex container. - Item widths are set in percentages, ensuring they remain fluid and scale relative to their parent container.
- Five default grid breakpoints are provided: xs, sm, md, lg, and xl. For custom breakpoints, see custom breakpoints grid.
- You can assign integer values to each breakpoint to specify how many of the 12 available columns a component occupies when the viewport width meets the breakpoint constraints.
- It uses the
gapCSS property to manage spacing between items. - It does not support row spanning, meaning child elements cannot span multiple rows. For this functionality, consider using CSS Grid.
- It does not feature automatic child placement. It places children sequentially, moving to the next line if space is insufficient. For auto-placement, use CSS Grid instead.
:::warning The
Grid component is designed for layout purposes, not as a data grid. For data grids, explore the MUI X DataGrid component. :::Fluid grids
Fluid grids employ columns that dynamically scale and resize content. Breakpoints can be used to determine when the layout requires significant adjustments.
Basic grid
To create a grid layout, you need a container. Use the
container prop to establish a grid container that encloses the grid items (the Grid is always an item).Column widths are defined as integer values between 1 and 12. For instance, an item with
size={6} spans half the width of the grid container.size=8
size=4
size=4
size=8
import * as React from 'react';
import { styled } from '@mui/material/styles';
import Box from '@mui/material/Box';
import Paper from '@mui/material/Paper';
import Grid from '@mui/material/Grid';
const Item = styled(Paper)(({ theme }) => ({
backgroundColor: '#fff',
...theme.typography.body2,
padding: theme.spacing(1),
textAlign: 'center',
color: (theme.vars ?? theme).palette.text.secondary,
...theme.applyStyles('dark', {
backgroundColor: '#1A2027',
}),
}));
export default function BasicGrid() {
return (
<Box sx={{ flexGrow: 1 }}>
<Grid container spacing={2}>
<Grid size={8}>
<Item>size=8</Item>
</Grid>
<Grid size={4}>
<Item>size=4</Item>
</Grid>
<Grid size={4}>
<Item>size=4</Item>
</Grid>
<Grid size={8}>
<Item>size=8</Item>
</Grid>
</Grid>
</Box>
);
}Multiple breakpoints
Items can have multiple defined widths, prompting layout changes at specific breakpoints. Width values apply to all larger breakpoints, with values for larger breakpoints overriding those for smaller ones.
For example, a component with
size={{ xs: 12, sm: 6 }} spans the full viewport width when the viewport is less than 600 pixels wide. Beyond this size, it occupies half the width—six columns instead of 12.xs=6 md=8
xs=6 md=4
xs=6 md=4
xs=6 md=8
import * as React from 'react';
import { styled } from '@mui/material/styles';
import Box from '@mui/material/Box';
import Paper from '@mui/material/Paper';
import Grid from '@mui/material/Grid';
const Item = styled(Paper)(({ theme }) => ({
backgroundColor: '#fff',
...theme.typography.body2,
padding: theme.spacing(1),
textAlign: 'center',
color: (theme.vars ?? theme).palette.text.secondary,
...theme.applyStyles('dark', {
backgroundColor: '#1A2027',
}),
}));
export default function FullWidthGrid() {
return (
<Box sx={{ flexGrow: 1 }}>
<Grid container spacing={2}>
<Grid size={{ xs: 6, md: 8 }}>
<Item>xs=6 md=8</Item>
</Grid>
<Grid size={{ xs: 6, md: 4 }}>
<Item>xs=6 md=4</Item>
</Grid>
<Grid size={{ xs: 6, md: 4 }}>
<Item>xs=6 md=4</Item>
</Grid>
<Grid size={{ xs: 6, md: 8 }}>
<Item>xs=6 md=8</Item>
</Grid>
</Grid>
</Box>
);
}Spacing
Control the spacing between child elements using the
spacing prop. This value can be any positive number (including decimals) or a string, and is converted into a CSS property via the theme.spacing() helper.The following example demonstrates the application of the
spacing prop:<Grid container spacing={2}>import * as React from 'react';
import Box from '@mui/material/Box';
import Grid from '@mui/material/Grid';
import FormLabel from '@mui/material/FormLabel';
import FormControl from '@mui/material/FormControl';
import FormControlLabel from '@mui/material/FormControlLabel';
import RadioGroup from '@mui/material/RadioGroup';
import Radio from '@mui/material/Radio';
import Paper from '@mui/material/Paper';
import { HighlightedCode } from '@/app/(public)/documentation/material-ui-components/utils/HighlightedCode';
export default function SpacingGrid() {
const [spacing, setSpacing] = React.useState(2);
const handleChange = (event: React.ChangeEvent<HTMLInputElement>) => {
setSpacing(Number((event.target as HTMLInputElement).value));
};
const jsx = `
<Grid container spacing={${spacing}}>
`;
return (
<Box
sx={{
flexGrow: 1,
display: 'flex',
flexDirection: 'column',
gap: 2,
pt: 2,
'&& pre': { margin: 0 },
}}
>
<Grid container justifyContent="center" spacing={spacing}>
{[0, 1, 2].map((value) => (
<Grid key={value}>
<Paper
sx={(theme) => ({
height: 140,
width: 100,
backgroundColor: '#fff',
...theme.applyStyles('dark', {
backgroundColor: '#1A2027',
}),
})}
/>
</Grid>
))}
</Grid>
<Paper sx={{ p: 2 }}>
<FormControl component="fieldset">
<FormLabel component="legend">spacing</FormLabel>
<RadioGroup
name="spacing"
aria-label="spacing"
value={spacing.toString()}
onChange={handleChange}
row
>
{[0, 0.5, 1, 2, 3, 4, 8, 12].map((value) => (
<FormControlLabel
key={value}
value={value.toString()}
control={<Radio />}
label={value.toString()}
/>
))}
</RadioGroup>
</FormControl>
</Paper>
<HighlightedCode code={jsx} language="jsx" />
</Box>
);
}Row and column spacing
The
rowSpacing and columnSpacing props allow independent specification of row and column gaps, akin to the row-gap and column-gap properties in CSS Grid.1
2
3
4
import * as React from 'react';
import { styled } from '@mui/material/styles';
import Grid from '@mui/material/Grid';
import Paper from '@mui/material/Paper';
import Box from '@mui/material/Box';
const Item = styled(Paper)(({ theme }) => ({
backgroundColor: '#fff',
...theme.typography.body2,
padding: theme.spacing(1),
textAlign: 'center',
color: (theme.vars ?? theme).palette.text.secondary,
...theme.applyStyles('dark', {
backgroundColor: '#1A2027',
}),
}));
export default function RowAndColumnSpacing() {
return (
<Box sx={{ width: '100%' }}>
<Grid container rowSpacing={1} columnSpacing={{ xs: 1, sm: 2, md: 3 }}>
<Grid size={6}>
<Item>1</Item>
</Grid>
<Grid size={6}>
<Item>2</Item>
</Grid>
<Grid size={6}>
<Item>3</Item>
</Grid>
<Grid size={6}>
<Item>4</Item>
</Grid>
</Grid>
</Box>
);
}Responsive values
Prop values can be adjusted dynamically based on the active breakpoint. For example, this enables the implementation of Material Design's recommended responsive layout grid, as shown in the following example:
1
2
3
4
5
6
import * as React from 'react';
import { styled } from '@mui/material/styles';
import Box from '@mui/material/Box';
import Paper from '@mui/material/Paper';
import Grid from '@mui/material/Grid';
const Item = styled(Paper)(({ theme }) => ({
backgroundColor: '#fff',
...theme.typography.body2,
padding: theme.spacing(2),
textAlign: 'center',
color: (theme.vars ?? theme).palette.text.secondary,
...theme.applyStyles('dark', {
backgroundColor: '#1A2027',
}),
}));
export default function ResponsiveGrid() {
return (
<Box sx={{ flexGrow: 1 }}>
<Grid container spacing={{ xs: 2, md: 3 }} columns={{ xs: 4, sm: 8, md: 12 }}>
{Array.from(Array(6)).map((_, index) => (
<Grid key={index} size={{ xs: 2, sm: 4, md: 4 }}>
<Item>{index + 1}</Item>
</Grid>
))}
</Grid>
</Box>
);
}