0
# Layout Components
1

2
Core React components for building layouts with system props support, responsive design capabilities, and theme integration. These components serve as the foundation for MUI System's layout system.
3

4
## Capabilities
5

6
### Box Component
7

8
Universal container component that accepts all system props and serves as the building block for other components.
9

10
```typescript { .api }
11
/**
12
 * Universal container component with all system props support
13
 * @param props - Box props including system props and sx
14
 * @returns Styled div element (or custom component)
15
 */
16
declare const Box: OverridableComponent<BoxTypeMap>;
17

18
interface BoxProps<
19
  RootComponent extends React.ElementType = 'div',
20
  AdditionalProps = {}
21
> {
22
  /** Child components */
23
  children?: React.ReactNode;
24
  
25
  /** Element type to render (default: 'div') */
26
  component?: React.ElementType;
27
  
28
  /** Advanced styling with theme access and responsive values */
29
  sx?: SxProps<Theme>;
30
  
31
  /** All system props (spacing, colors, typography, etc.) */
32
  [key: string]: any;
33
}
34

35
interface BoxTypeMap<
36
  AdditionalProps = {},
37
  RootComponent extends React.ElementType = 'div',
38
  Theme extends object = Theme
39
> {
40
  props: AdditionalProps & BoxOwnProps<Theme>;
41
  defaultComponent: RootComponent;
42
}
43

44
interface BoxOwnProps<Theme extends object = Theme> extends SystemProps<Theme> {
45
  children?: React.ReactNode;
46
  ref?: React.Ref<unknown>;
47
  sx?: SxProps<Theme>;
48
}
49

50
// CSS classes for Box component
51
const boxClasses: {
52
  root: string;
53
};
54
```
55

56
**Usage Examples:**
57

58
```typescript
59
import { Box } from "@mui/system";
60

61
// Basic usage with system props
62
<Box p={2} m={1} bgcolor="primary.main" color="white">
63
  Content
64
</Box>
65

66
// Responsive values
67
<Box
68
  width={{ xs: '100%', sm: '50%', md: '25%' }}
69
  p={{ xs: 1, sm: 2, md: 3 }}
70
>
71
  Responsive box
72
</Box>
73

74
// Using sx prop for advanced styling
75
<Box
76
  sx={{
77
    width: 300,
78
    '&:hover': {
79
      backgroundColor: 'grey.100',
80
      transform: 'scale(1.05)',
81
    },
82
    '@media (max-width: 600px)': {
83
      width: '100%',
84
    },
85
  }}
86
>
87
  Advanced styling
88
</Box>
89

90
// Custom component
91
<Box component="section" p={2}>
92
  Renders as section element
93
</Box>
94
```
95

96
### Container Component
97

98
Responsive container component that centers content and applies max-width constraints based on breakpoints.
99

100
```typescript { .api }
101
/**
102
 * Responsive container component with max-width constraints
103
 * @param props - Container props
104
 * @returns Centered container element
105
 */
106
declare const Container: OverridableComponent<ContainerTypeMap>;
107

108
interface ContainerProps<
109
  RootComponent extends React.ElementType = 'div',
110
  AdditionalProps = {}
111
> {
112
  /** Child components */
113
  children?: React.ReactNode;
114
  
115
  /** Maximum width constraint */
116
  maxWidth?: 'xs' | 'sm' | 'md' | 'lg' | 'xl' | false;
117
  
118
  /** Whether to use fixed max-width instead of responsive */
119
  fixed?: boolean;
120
  
121
  /** Remove horizontal padding */
122
  disableGutters?: boolean;
123
  
124
  /** CSS classes override */
125
  classes?: Partial<ContainerClasses>;
126
  
127
  /** Advanced styling */
128
  sx?: SxProps<Theme>;
129
  
130
  /** Element type to render */
131
  component?: React.ElementType;
132
}
133

134
interface ContainerTypeMap<
135
  AdditionalProps = {},
136
  RootComponent extends React.ElementType = 'div'
137
> {
138
  props: AdditionalProps & ContainerProps;
139
  defaultComponent: RootComponent;
140
}
141

142
// CSS classes for Container component
143
const containerClasses: {
144
  root: string;
145
  disableGutters: string;
146
  fixed: string;
147
  maxWidthXs: string;
148
  maxWidthSm: string;
149
  maxWidthMd: string;
150
  maxWidthLg: string;
151
  maxWidthXl: string;
152
};
153

154
/**
155
 * Factory function for creating custom container components
156
 * @param options - Container creation options
157
 * @returns Custom container component
158
 */
159
function createContainer<Theme extends object = Theme>(
160
  options?: CreateContainerOptions<Theme>
161
): React.ComponentType<ContainerProps>;
162

163
interface CreateContainerOptions<Theme> {
164
  createStyledComponent?: CreateStyledComponent<Theme>;
165
  useThemeProps?: (props: any) => any;
166
  componentName?: string;
167
}
168
```
169

170
**Usage Examples:**
171

172
```typescript
173
import { Container } from "@mui/system";
174

175
// Basic container
176
<Container>
177
  <p>This content is centered and has max-width constraints</p>
178
</Container>
179

180
// Fixed max-width
181
<Container maxWidth="md">
182
  <p>Fixed to medium breakpoint width</p>
183
</Container>
184

185
// Full width container
186
<Container maxWidth={false}>
187
  <p>No max-width constraint</p>
188
</Container>
189

190
// No gutters
191
<Container disableGutters>
192
  <p>No horizontal padding</p>
193
</Container>
194
```
195

196
### Grid Component
197

198
Modern CSS Grid layout system with responsive capabilities and flexible configuration options.
199

200
```typescript { .api }
201
/**
202
 * CSS Grid layout component with responsive capabilities
203
 * @param props - Grid props
204
 * @returns Grid container or item element
205
 */
206
declare const Grid: React.ComponentType<GridProps>;
207

208
interface GridProps<
209
  RootComponent extends React.ElementType = 'div',
210
  AdditionalProps = {}
211
> extends SystemProps<Theme> {
212
  /** Child components */
213
  children?: React.ReactNode;
214
  
215
  /** Whether this is a grid container */
216
  container?: boolean;
217
  
218
  /** Grid item size (1-12 or auto/grow) */
219
  size?: ResponsiveStyleValue<GridSize>;
220
  
221
  /** Grid item offset */
222
  offset?: ResponsiveStyleValue<GridOffset>;
223
  
224
  /** Grid container spacing (applies to both column and row spacing) */
225
  spacing?: ResponsiveStyleValue<GridSpacing>;
226
  
227
  /** Grid container horizontal spacing (overrides spacing) */
228
  columnSpacing?: ResponsiveStyleValue<GridSpacing>;
229
  
230
  /** Grid container vertical spacing (overrides spacing) */
231
  rowSpacing?: ResponsiveStyleValue<GridSpacing>;
232
  
233
  /** Grid container columns (default: 12) */
234
  columns?: ResponsiveStyleValue<number>;
235
  
236
  /** Grid container direction (default: 'row') */
237
  direction?: ResponsiveStyleValue<GridDirection>;
238
  
239
  /** Grid container wrapping (default: 'wrap') */
240
  wrap?: GridWrap;
241
  
242
  /** Internal nesting level (starts at 0, increases with nested containers) */
243
  unstable_level?: number;
244
  
245
  /** CSS classes override */
246
  classes?: Partial<GridClasses>;
247
  
248
  /** Advanced styling */
249
  sx?: SxProps<Theme>;
250
  
251
  /** Element type to render */
252
  component?: React.ElementType;
253
}
254

255
// Grid type definitions
256
type GridSize = 'auto' | 'grow' | number | false;
257
type GridOffset = 'auto' | number;
258
type GridSpacing = number | string;
259
type GridDirection = 'row' | 'row-reverse' | 'column' | 'column-reverse';
260
type GridWrap = 'nowrap' | 'wrap' | 'wrap-reverse';
261

262
// CSS classes for Grid component
263
const gridClasses: {
264
  root: string;
265
  container: string;
266
  item: string;
267
  zeroMinWidth: string;
268
  [key: string]: string;
269
};
270

271
/**
272
 * Factory function for creating custom grid components
273
 * @param options - Grid creation options
274
 * @returns Custom grid component
275
 */
276
function createGrid<Theme extends object = Theme>(
277
  options?: CreateGridOptions<Theme>
278
): React.ComponentType<GridProps>;
279

280
interface CreateGridOptions<Theme> {
281
  createStyledComponent?: CreateStyledComponent<Theme>;
282
  useThemeProps?: (props: any) => any;
283
  componentName?: string;
284
}
285
```
286

287
**Usage Examples:**
288

289
```typescript
290
import { Grid } from "@mui/system";
291

292
// Grid container with spacing
293
<Grid container spacing={2}>
294
  <Grid size={6}>
295
    <p>Half width item</p>
296
  </Grid>
297
  <Grid size={6}>
298
    <p>Half width item</p>
299
  </Grid>
300
</Grid>
301

302
// Responsive grid sizes
303
<Grid container spacing={{ xs: 1, sm: 2, md: 3 }}>
304
  <Grid size={{ xs: 12, sm: 6, md: 4 }}>
305
    <p>Responsive item</p>
306
  </Grid>
307
  <Grid size={{ xs: 12, sm: 6, md: 8 }}>
308
    <p>Responsive item</p>
309
  </Grid>
310
</Grid>
311

312
// Grid with offset
313
<Grid container>
314
  <Grid size={4} offset={2}>
315
    <p>Offset item</p>
316
  </Grid>
317
</Grid>
318

319
// Auto-sizing and grow
320
<Grid container>
321
  <Grid size="auto">
322
    <p>Auto width</p>
323
  </Grid>
324
  <Grid size="grow">
325
    <p>Takes remaining space</p>
326
  </Grid>
327
</Grid>
328
```
329

330
### Stack Component
331

332
One-dimensional layout component for arranging items in a single direction with consistent spacing.
333

334
```typescript { .api }
335
/**
336
 * One-dimensional layout component with spacing
337
 * @param props - Stack props
338
 * @returns Flexbox container element
339
 */
340
declare const Stack: React.ComponentType<StackProps>;
341

342
interface StackProps<
343
  RootComponent extends React.ElementType = 'div',
344
  AdditionalProps = {}
345
> {
346
  /** Child components */
347
  children?: React.ReactNode;
348
  
349
  /** Layout direction */
350
  direction?: StackDirection | ResponsiveStyleValue<StackDirection>;
351
  
352
  /** Spacing between items */
353
  spacing?: number | string | ResponsiveStyleValue<number | string>;
354
  
355
  /** Divider element between items */
356
  divider?: React.ReactNode;
357
  
358
  /** Use CSS gap instead of margin for spacing */
359
  useFlexGap?: boolean;
360
  
361
  /** CSS classes override */
362
  classes?: Partial<StackClasses>;
363
  
364
  /** Advanced styling */
365
  sx?: SxProps<Theme>;
366
  
367
  /** Element type to render */
368
  component?: React.ElementType;
369
}
370

371
type StackDirection = 'row' | 'row-reverse' | 'column' | 'column-reverse';
372

373
// CSS classes for Stack component
374
const stackClasses: {
375
  root: string;
376
};
377

378
/**
379
 * Factory function for creating custom stack components
380
 * @param options - Stack creation options
381
 * @returns Custom stack component
382
 */
383
function createStack<Theme extends object = Theme>(
384
  options?: CreateStackOptions<Theme>
385
): React.ComponentType<StackProps>;
386

387
interface CreateStackOptions<Theme> {
388
  createStyledComponent?: CreateStyledComponent<Theme>;
389
  useThemeProps?: (props: any) => any;
390
  componentName?: string;
391
}
392
```
393

394
**Usage Examples:**
395

396
```typescript
397
import { Stack, Divider } from "@mui/system";
398

399
// Vertical stack with spacing
400
<Stack spacing={2}>
401
  <div>Item 1</div>
402
  <div>Item 2</div>
403
  <div>Item 3</div>
404
</Stack>
405

406
// Horizontal stack
407
<Stack direction="row" spacing={1}>
408
  <button>Button 1</button>
409
  <button>Button 2</button>
410
  <button>Button 3</button>
411
</Stack>
412

413
// Stack with dividers
414
<Stack spacing={1} divider={<Divider />}>
415
  <div>Section 1</div>
416
  <div>Section 2</div>
417
  <div>Section 3</div>
418
</Stack>
419

420
// Responsive direction and spacing
421
<Stack
422
  direction={{ xs: 'column', sm: 'row' }}
423
  spacing={{ xs: 1, sm: 2, md: 4 }}
424
>
425
  <div>Responsive item 1</div>
426
  <div>Responsive item 2</div>
427
</Stack>
428

429
// Using flexbox gap
430
<Stack direction="row" spacing={2} useFlexGap>
431
  <div>Gap item 1</div>
432
  <div>Gap item 2</div>
433
</Stack>
434
```
435

436
## Component Integration
437

438
All layout components integrate seamlessly with:
439

440
- **System Props**: All CSS properties available as props with theme integration
441
- **sx Prop**: Advanced styling with pseudo-selectors, media queries, and theme access
442
- **Theme Provider**: Automatic theme context access for consistent styling
443
- **Responsive Values**: Object syntax for breakpoint-specific values
444
- **TypeScript**: Full type safety with generic component types and prop interfaces
445

446
The components also support component composition and can be used as building blocks for more complex layout patterns.