0
# Masonry Layout
1

2
Pinterest-style masonry layout component with responsive column configuration, flexible spacing options, and optimized rendering for dynamic content grids.
3

4
## Capabilities
5

6
### Masonry Component
7

8
Creates a masonry layout that automatically arranges child elements in columns with optimal vertical spacing.
9

10
```typescript { .api }
11
/**
12
 * Pinterest-style masonry layout component
13
 * @param props - Masonry configuration props
14
 * @returns Masonry layout container
15
 */
16
function Masonry(props: MasonryProps): JSX.Element;
17

18
interface MasonryProps extends StandardProps<React.HTMLAttributes<HTMLDivElement>> {
19
  /** Child elements to arrange in masonry layout (required) */
20
  children: NonNullable<React.ReactNode>;
21
  /** CSS classes for styling customization */
22
  classes?: Partial<MasonryClasses>;
23
  /** Number of columns or responsive breakpoint object (default: 4) */
24
  columns?: ResponsiveStyleValue<number | string>;
25
  /** Default number of columns for SSR (server-side rendering) */
26
  defaultColumns?: number;
27
  /** Default height for SSR calculations */
28
  defaultHeight?: number;
29
  /** Default spacing for SSR calculations */
30
  defaultSpacing?: number;
31
  /** Spacing between items or responsive spacing object (default: 1) */
32
  spacing?: ResponsiveStyleValue<number | string>;
33
  /** Use sequential column assignment instead of shortest column (default: false) */
34
  sequential?: boolean;
35
  /** System prop for styling */
36
  sx?: SxProps<Theme>;
37
}
38

39
interface MasonryClasses {
40
  /** Class applied to the root element */
41
  root: string;
42
}
43
```
44

45
**Usage Examples:**
46

47
```typescript
48
import React from 'react';
49
import { Masonry } from '@mui/lab';
50
import { Card, CardContent, Typography } from '@mui/material';
51

52
// Basic masonry layout
53
function BasicMasonry() {
54
  const items = [
55
    { height: 150, title: 'Item 1' },
56
    { height: 200, title: 'Item 2' },
57
    { height: 100, title: 'Item 3' },
58
    // ... more items
59
  ];
60

61
  return (
62
    <Masonry columns={3} spacing={2}>
63
      {items.map((item, index) => (
64
        <Card key={index} sx={{ height: item.height }}>
65
          <CardContent>
66
            <Typography variant="h6">{item.title}</Typography>
67
          </CardContent>
68
        </Card>
69
      ))}
70
    </Masonry>
71
  );
72
}
73

74
// Responsive masonry with breakpoint-specific columns
75
function ResponsiveMasonry() {
76
  return (
77
    <Masonry
78
      columns={{
79
        xs: 1,
80
        sm: 2,
81
        md: 3,
82
        lg: 4,
83
        xl: 5
84
      }}
85
      spacing={{
86
        xs: 1,
87
        sm: 2,
88
        md: 3
89
      }}
90
    >
91
      {children}
92
    </Masonry>
93
  );
94
}
95

96
// Sequential column assignment (left-to-right instead of shortest-first)
97
function SequentialMasonry() {
98
  return (
99
    <Masonry columns={4} spacing={2} sequential={true}>
100
      {children}
101
    </Masonry>
102
  );
103
}
104
```
105

106
### Responsive Configuration
107

108
Masonry supports responsive breakpoint values for both columns and spacing:
109

110
```typescript { .api }
111
// Responsive value type supporting Material-UI breakpoints
112
type ResponsiveStyleValue<T> = T | {
113
  xs?: T;  // 0px and up
114
  sm?: T;  // 600px and up  
115
  md?: T;  // 900px and up
116
  lg?: T;  // 1200px and up
117
  xl?: T;  // 1536px and up
118
};
119
```
120

121
### Server-Side Rendering Support
122

123
For applications using SSR, provide default values to prevent hydration mismatches:
124

125
```typescript
126
function SSRMasonry() {
127
  return (
128
    <Masonry
129
      columns={{ xs: 1, sm: 2, md: 3 }}
130
      spacing={2}
131
      defaultColumns={2}
132
      defaultHeight={200}
133
      defaultSpacing={16}
134
    >
135
      {children}
136
    </Masonry>
137
  );
138
}
139
```
140

141
### Utility Functions
142

143
Helper functions available for masonry calculations:
144

145
```typescript { .api }
146
/**
147
 * Parse string or number value to number for calculations
148
 * @param val - String or number value to parse
149
 * @returns Parsed number value
150
 */
151
function parseToNumber(val: string | number): number;
152

153
/**
154
 * Generate CSS styles for masonry layout
155
 * @param options - Style generation options
156
 * @returns CSS style object
157
 */
158
function getStyle(options: {
159
  ownerState: MasonryProps;
160
  theme: Theme;
161
}): React.CSSProperties;
162
```
163

164
## Layout Behavior
165

166
### Column Assignment
167

168
**Shortest Column (default)**: Items are placed in the column with the least current height, creating a more balanced layout.
169

170
**Sequential**: Items are placed left-to-right in order, which may create uneven column heights but preserves order.
171

172
```typescript
173
// Balanced height distribution (default)
174
<Masonry columns={3} sequential={false}>
175

176
// Preserves left-to-right order
177
<Masonry columns={3} sequential={true}>
178
```
179

180
### Spacing Calculation
181

182
Spacing values are multiplied by the theme's spacing function:
183
- `spacing={1}` = `theme.spacing(1)` (typically 8px)
184
- `spacing={2}` = `theme.spacing(2)` (typically 16px)
185

186
## CSS Classes
187

188
```typescript { .api }
189
// Available CSS classes for Masonry
190
const masonryClasses: {
191
  root: string;
192
};
193
```
194

195
## Performance Considerations
196

197
- Masonry recalculates layout on window resize and content changes
198
- Use `React.memo()` for child components to prevent unnecessary re-renders
199
- Consider virtualization for large datasets (500+ items)
200
- SSR defaults help prevent layout shifts during hydration