Grid

Create responsive row-based layout with native size, offset and spacing.

This guide covers Material UI Core with the default Emotion engine; extensions and additional demos are explicitly classified.

Use case and business boundary

Grid is not masonry or a data grid; this version's size API is not the old xs/item API or PigmentGrid setup.

Native composition and scope

Grid

Preserve native Material UI composition and types; do not substitute JGuang UI/Base UI/Radix APIs. Example entries are not extra components.

Excluded integrations: PigmentGrid (@mui/material-pigment-css). Not claimed verified in the default Emotion environment.

Native installation and initialization

npm install @mui/material@9.4.0 @emotion/react@11.14.0 @emotion/styled@11.14.1

Use native npm and Emotion, not an invented JGuang UI Registry URL. Place examples inside native ThemeProvider; choose CssBaseline or ScopedCssBaseline for the project. Inspect React, existing providers, lockfile and SSR first. Never overwrite files or conceal peer conflicts. This batch verified React 19.2.8; React 18 and below require matching react-is. See the included bilingual setup guide.

Practical native parameters

These selected parameters are not a flattened universal API. Preserve the native declaring owner, slot structure, nullable values and generics.

Runnable native examples

Machine keys select example entries, not universal variant props. Native demo JSX/data stay unchanged; JGuang-authored acceptance fixtures are explicitly labelled.

• Basic grid · BasicGrid · upstream native demo
• Multiple breakpoints · FullWidthGrid · upstream native demo
• Row and column spacing · RowAndColumnSpacing · upstream native demo
• Responsive values · ResponsiveGrid · upstream native demo
• Auto-layout · AutoGrid · upstream native demo
• Variable width content · VariableWidthGrid · upstream native demo
• Inheriting spacing · NestedGrid · upstream native demo
• Inheriting columns · NestedGridColumns · upstream native demo
• Columns · ColumnsGrid · upstream native demo
• Offset · OffsetGrid · upstream native demo
• Centered elements · CenteredElementGrid · upstream native demo
• Full border · FullBorderedGrid · upstream native demo
• Half border · HalfBorderedGrid · upstream native demo
• Column direction · ColumnLayoutInsideGrid · upstream native demo

Explicitly unsupported additional examples

These remain in the upstream inventory, not silently skipped or presented as working previews. Additional dependency/framework acceptance is required.

• Spacing · SpacingGrid: @mui/internal-core-docs/HighlightedCode
• Interactive · InteractiveGrid: @mui/internal-core-docs/HighlightedCode

Actual usage example

Unmodified pinned native demo; copy its required local helper files together.

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>
  );
}

Example dependency boundaries

@mui/material/styles, @mui/material/Box, @mui/material/Paper, @mui/material/Grid, @mui/material/Avatar, @mui/material/Stack

Direct Icons/System/Utils example imports require their matching 9.4.0 packages. Relative data/helpers are part of the example closure, not extra components. Remote images and simulated operations do not supply a backend.

Pinned upstream API metadata reference

These tables retain the upstream metadata, not a newly inferred generic type system. Conditional generics, inherited props and callback details are defined by the source declarations below. Theme defaults may override metadata defaults.

Grid

import Grid from '@mui/material/Grid';
import { Grid } from '@mui/material';

Native source declarations

Declarations/imports are extracted from pinned source without flattening unions or external inheritance. Original English comments/types are source reference, not a claim of translated upstream prose. Shared types stay in their native packages.

vendor/src/Grid/Grid.tsx

import PropTypes from 'prop-types';

import { createGrid } from '@mui/system/Grid';

import { SxProps } from '@mui/system';

import { OverridableComponent, OverrideProps } from '@mui/types';

import requirePropFactory from '../utils/requirePropFactory';

import { Theme, styled, Breakpoint } from '../styles';

import { useDefaultProps } from '../DefaultPropsProvider';

import useTheme from '../styles/useTheme';

type ResponsiveStyleValue<T> = T | Array<T | null> | { [key in Breakpoint]?: T | null };

export type GridDirection = 'row' | 'row-reverse';

export type GridSpacing = number | string;

export type GridWrap = 'nowrap' | 'wrap' | 'wrap-reverse';

export type GridSize = 'auto' | 'grow' | number | false;

export type GridOffset = 'auto' | number;

export interface GridBaseProps {
  /**
   * The content of the component.
   */
  children?: React.ReactNode;
  /**
   * The number of columns.
   * @default 12
   */
  columns?: ResponsiveStyleValue<number> | undefined;
  /**
   * Defines the horizontal space between the type `item` components.
   * It overrides the value of the `spacing` prop.
   */
  columnSpacing?: ResponsiveStyleValue<GridSpacing> | undefined;
  /**
   * If `true`, the component will have the flex *container* behavior.
   * You should be wrapping *items* with a *container*.
   * @default false
   */
  container?: boolean | undefined;
  /**
   * Defines the `flex-direction` style property for the container.
   *
   * ⚠️ Only `row` and `row-reverse` are supported. `column` and `column-reverse` are not supported,
   * because the Grid component is designed to subdivide layouts into **columns**, not rows.
   *
   * For vertical layouts, use `Stack` instead.
   *
   * @default 'row'
   */
  direction?: ResponsiveStyleValue<GridDirection> | undefined;
  /**
   * Defines the offset value for the type `item` components.
   */
  offset?: ResponsiveStyleValue<GridOffset> | undefined;
  /**
   * @internal
   * The level of the grid starts from `0` and increases when the grid nests
   * inside another grid. Nesting is defined as a container Grid being a direct
   * child of a container Grid.
   *
   * ```js
   * <Grid container> // level 0
   *   <Grid container> // level 1
   *     <Grid container> // level 2
   * ```
   *
   * Only consecutive grid is considered nesting. A grid container will start at
   * `0` if there are non-Grid container element above it.
   *
   * ```js
   * <Grid container> // level 0
   *   <div>
   *     <Grid container> // level 0
   * ```
   *
   * ```js
   * <Grid container> // level 0
   *   <Grid>
   *     <Grid container> // level 0
   * ```
   */
  unstable_level?: number | undefined;
  /**
   * Defines the vertical space between the type `item` components.
   * It overrides the value of the `spacing` prop.
   */
  rowSpacing?: ResponsiveStyleValue<GridSpacing> | undefined;
  /**
   * Defines the size of the the type `item` components.
   */
  size?: ResponsiveStyleValue<GridSize> | undefined;
  /**
   * Defines the space between the type `item` components.
   * It can only be used on a type `container` component.
   * @default 0
   */
  spacing?: ResponsiveStyleValue<GridSpacing> | undefined;
  /**
   * Defines the `flex-wrap` style property.
   * It's applied for all screen sizes.
   * @default 'wrap'
   */
  wrap?: GridWrap | undefined;
}

export interface GridTypeMap<P = {}, D extends React.ElementType = 'div'> {
  props: P & GridBaseProps & { sx?: SxProps<Theme> | undefined };
  defaultComponent: D;
}

export type GridProps<
  D extends React.ElementType = GridTypeMap['defaultComponent'],
  P = {
    component?: React.ElementType | undefined;
  },
> = OverrideProps<GridTypeMap<P, D>, D>;

Post-install acceptance

Run strict types, production build and real interactions. Check keyboard labels/focus, disabled/error/read-only semantics where natively supported, both themes, narrow screens and reduced motion. Verify callbacks against the real host data; do not declare installation complete from copying a prompt. Initialization fixtures also require server HTML and warning-free hydration.

Source and license

https://github.com/mui/material-ui/tree/809a7717b4c050ba3f69b75300689f07c050a16e

MIT · @mui/material@9.4.0. Vendor originals and license are preserved. Full original upstream prose remains in vendor/docs and is not represented as fully translated.