0
# Surface Components
1

2
Surface components provide Material Design elevation and content organization through Paper surfaces, expandable accordions, and informational badges and tooltips.
3

4
## Capabilities
5

6
### Paper
7

8
Basic surface component providing Material Design elevation and background styling.
9

10
```typescript { .api }
11
/**
12
 * Basic surface component with Material Design elevation
13
 * @param props - Paper component props
14
 * @returns JSX.Element - Paper component
15
 */
16
function Paper(props: PaperProps): JSX.Element;
17

18
interface PaperProps extends CommonProps {
19
  /** The component used for the root node */
20
  component?: React.ElementType;
21
  /** Shadow depth of component (0-24) */
22
  elevation?: number;
23
  /** If true, rounded corners are disabled */
24
  square?: boolean;
25
  /** The variant to use */
26
  variant?: 'elevation' | 'outlined';
27
  /** The content of the component */
28
  children?: React.ReactNode;
29
}
30
```
31

32
**Usage Examples:**
33

34
```typescript
35
import { Paper } from "@mui/material";
36

37
// Basic paper with elevation
38
<Paper elevation={3}>
39
  <p>This content is displayed on a raised surface</p>
40
</Paper>
41

42
// Outlined paper variant
43
<Paper variant="outlined">
44
  <p>This content has an outline instead of shadow</p>
45
</Paper>
46

47
// Square paper without rounded corners
48
<Paper square elevation={1}>
49
  <p>Sharp corners paper</p>
50
</Paper>
51
```
52

53
### Accordion
54

55
Expandable panels for organizing content into collapsible sections.
56

57
```typescript { .api }
58
/**
59
 * Expandable panels for organizing content
60
 * @param props - Accordion component props
61
 * @returns JSX.Element - Accordion component
62
 */
63
function Accordion(props: AccordionProps): JSX.Element;
64

65
interface AccordionProps extends CommonProps {
66
  /** The content of the component */
67
  children?: React.ReactNode;
68
  /** If true, expands the accordion by default */
69
  defaultExpanded?: boolean;
70
  /** If true, the component is disabled */
71
  disabled?: boolean;
72
  /** If true, it removes the margin between two expanded accordion items */
73
  disableGutters?: boolean;
74
  /** If true, expands the accordion, otherwise collapse it */
75
  expanded?: boolean;
76
  /** Callback fired when the expand/collapse state is changed */
77
  onChange?: (event: React.SyntheticEvent, expanded: boolean) => void;
78
  /** If true, rounded corners are disabled */
79
  square?: boolean;
80
  /** The component used for the transition */
81
  TransitionComponent?: React.ComponentType<any>;
82
  /** Props applied to the transition element */
83
  TransitionProps?: object;
84
}
85
```
86

87
### Accordion Summary
88

89
Header area of accordion with expand/collapse functionality.
90

91
```typescript { .api }
92
/**
93
 * Header area of accordion with expand/collapse
94
 * @param props - AccordionSummary component props
95
 * @returns JSX.Element - AccordionSummary component
96
 */
97
function AccordionSummary(props: AccordionSummaryProps): JSX.Element;
98

99
interface AccordionSummaryProps extends CommonProps {
100
  /** The content of the component */
101
  children?: React.ReactNode;
102
  /** The icon to display as the expand indicator */
103
  expandIcon?: React.ReactNode;
104
  /** This prop can help identify which element has keyboard focus */
105
  focusVisibleClassName?: string;
106
}
107
```
108

109
### Accordion Details
110

111
Content area of accordion that shows/hides based on expanded state.
112

113
```typescript { .api }
114
/**
115
 * Content area of accordion
116
 * @param props - AccordionDetails component props
117
 * @returns JSX.Element - AccordionDetails component
118
 */
119
function AccordionDetails(props: AccordionDetailsProps): JSX.Element;
120

121
interface AccordionDetailsProps extends CommonProps {
122
  /** The content of the component */
123
  children?: React.ReactNode;
124
}
125
```
126

127
### Accordion Actions
128

129
Container for accordion actions like buttons.
130

131
```typescript { .api }
132
/**
133
 * Container for accordion actions
134
 * @param props - AccordionActions component props
135
 * @returns JSX.Element - AccordionActions component
136
 */
137
function AccordionActions(props: AccordionActionsProps): JSX.Element;
138

139
interface AccordionActionsProps extends CommonProps {
140
  /** The content of the component */
141
  children?: React.ReactNode;
142
  /** If true, the actions do not have additional margin */
143
  disableSpacing?: boolean;
144
}
145
```
146

147
**Usage Examples:**
148

149
```typescript
150
import { 
151
  Accordion, 
152
  AccordionSummary, 
153
  AccordionDetails, 
154
  AccordionActions,
155
  Typography,
156
  Button
157
} from "@mui/material";
158
import ExpandMoreIcon from "@mui/icons-material/ExpandMore";
159

160
// Basic accordion
161
<Accordion>
162
  <AccordionSummary expandIcon={<ExpandMoreIcon />}>
163
    <Typography>Accordion 1</Typography>
164
  </AccordionSummary>
165
  <AccordionDetails>
166
    <Typography>
167
      Lorem ipsum dolor sit amet, consectetur adipiscing elit.
168
    </Typography>
169
  </AccordionDetails>
170
</Accordion>
171

172
// Accordion with actions
173
<Accordion>
174
  <AccordionSummary expandIcon={<ExpandMoreIcon />}>
175
    <Typography>Settings</Typography>
176
  </AccordionSummary>
177
  <AccordionDetails>
178
    <Typography>Configure your preferences here.</Typography>
179
  </AccordionDetails>
180
  <AccordionActions>
181
    <Button>Cancel</Button>
182
    <Button>Save</Button>
183
  </AccordionActions>
184
</Accordion>
185
```
186

187
### Badge
188

189
Component for displaying small amounts of data, typically numbers or status indicators.
190

191
```typescript { .api }
192
/**
193
 * Badge for displaying small amounts of data
194
 * @param props - Badge component props
195
 * @returns JSX.Element - Badge component
196
 */
197
function Badge(props: BadgeProps): JSX.Element;
198

199
interface BadgeProps extends CommonProps {
200
  /** The anchor of the badge */
201
  anchorOrigin?: {
202
    horizontal: 'left' | 'right';
203
    vertical: 'bottom' | 'top';
204
  };
205
  /** The content rendered within the badge */
206
  badgeContent?: React.ReactNode;
207
  /** The content rendered within the badge wrapper */
208
  children?: React.ReactNode;
209
  /** The color of the component */
210
  color?: 'default' | 'primary' | 'secondary' | 'error' | 'info' | 'success' | 'warning';
211
  /** The component used for the root node */
212
  component?: React.ElementType;
213
  /** If true, the badge is invisible */
214
  invisible?: boolean;
215
  /** Max count to show */
216
  max?: number;
217
  /** Wrapped shape the badge should overlap */
218
  overlap?: 'circular' | 'rectangular';
219
  /** Controls whether the badge is hidden when badgeContent is zero */
220
  showZero?: boolean;
221
  /** The variant to use */
222
  variant?: 'dot' | 'standard';
223
}
224
```
225

226
**Usage Examples:**
227

228
```typescript
229
import { Badge, Avatar, Icon } from "@mui/material";
230
import NotificationsIcon from "@mui/icons-material/Notifications";
231

232
// Basic badge with number
233
<Badge badgeContent={4} color="primary">
234
  <NotificationsIcon />
235
</Badge>
236

237
// Badge with maximum count
238
<Badge badgeContent={100} max={99} color="secondary">
239
  <NotificationsIcon />
240
</Badge>
241

242
// Dot badge
243
<Badge variant="dot" color="error">
244
  <Avatar src="/avatar.jpg" />
245
</Badge>
246
```
247

248
### Tooltip
249

250
Component for displaying additional information when hovering over or focusing on an element.
251

252
```typescript { .api }
253
/**
254
 * Tooltip for additional information
255
 * @param props - Tooltip component props
256
 * @returns JSX.Element - Tooltip component
257
 */
258
function Tooltip(props: TooltipProps): JSX.Element;
259

260
interface TooltipProps extends CommonProps {
261
  /** If true, adds an arrow to the tooltip */
262
  arrow?: boolean;
263
  /** Tooltip reference element */
264
  children: React.ReactElement;
265
  /** Do not respond to focus-visible events */
266
  disableFocusListener?: boolean;
267
  /** Do not respond to hover events */
268
  disableHoverListener?: boolean;
269
  /** Makes a tooltip not interactive */
270
  disableInteractive?: boolean;
271
  /** Do not respond to long press touch events */
272
  disableTouchListener?: boolean;
273
  /** The number of milliseconds to wait before showing the tooltip */
274
  enterDelay?: number;
275
  /** The number of milliseconds to wait before hiding the tooltip */
276
  leaveDelay?: number;
277
  /** Callback fired when the component is closed */
278
  onClose?: (event: React.SyntheticEvent) => void;
279
  /** Callback fired when the component is opened */
280
  onOpen?: (event: React.SyntheticEvent) => void;
281
  /** If true, the component is shown */
282
  open?: boolean;
283
  /** Tooltip placement */
284
  placement?: 'bottom-end' | 'bottom-start' | 'bottom' | 'left-end' | 'left-start' | 'left' | 'right-end' | 'right-start' | 'right' | 'top-end' | 'top-start' | 'top';
285
  /** Tooltip title. Zero-length titles string are never displayed */
286
  title: React.ReactNode;
287
  /** The component used for the transition */
288
  TransitionComponent?: React.ComponentType<any>;
289
  /** Props applied to the transition element */
290
  TransitionProps?: object;
291
}
292
```
293

294
**Usage Examples:**
295

296
```typescript
297
import { Tooltip, Button, IconButton } from "@mui/material";
298
import DeleteIcon from "@mui/icons-material/Delete";
299

300
// Basic tooltip
301
<Tooltip title="Delete">
302
  <IconButton>
303
    <DeleteIcon />
304
  </IconButton>
305
</Tooltip>
306

307
// Tooltip with arrow and custom placement
308
<Tooltip title="Add" arrow placement="top">
309
  <Button>Hover me</Button>
310
</Tooltip>
311

312
// Controlled tooltip
313
<Tooltip title="Controlled tooltip" open={open}>
314
  <Button onMouseEnter={() => setOpen(true)} onMouseLeave={() => setOpen(false)}>
315
    Controlled
316
  </Button>
317
</Tooltip>
318
```
319

320
## Common Types
321

322
```typescript { .api }
323
// Common props shared by surface components
324
interface CommonProps {
325
  className?: string;
326
  style?: React.CSSProperties;
327
  sx?: SxProps<Theme>;
328
}
329

330
// Anchor origin for badge positioning
331
interface AnchorOrigin {
332
  horizontal: 'left' | 'right';
333
  vertical: 'bottom' | 'top';
334
}
335

336
// Tooltip placement options
337
type TooltipPlacement = 
338
  | 'bottom-end' | 'bottom-start' | 'bottom'
339
  | 'left-end' | 'left-start' | 'left'
340
  | 'right-end' | 'right-start' | 'right'
341
  | 'top-end' | 'top-start' | 'top';
342
```