0
# Selection & Navigation
1

2
Components for user selection and navigation including dropdowns, menus, tabs, and their associated context providers with full keyboard navigation and accessibility support.
3

4
## Capabilities
5

6
### Select Component
7

8
Headless select dropdown component with single and multiple selection support.
9

10
```typescript { .api }
11
/**
12
 * Headless select dropdown component with single/multiple selection
13
 * @param props - Select properties including options, value, and event handlers
14
 * @returns Select element with dropdown functionality
15
 */
16
function Select<OptionValue, Multiple extends boolean = false>(
17
  props: SelectProps<OptionValue, Multiple>
18
): JSX.Element;
19

20
interface SelectProps<OptionValue, Multiple extends boolean = false>
21
  extends PolymorphicProps<SelectTypeMap<OptionValue, Multiple>, React.ElementType> {
22
  /** Whether to auto-focus on mount */
23
  autoFocus?: boolean;
24
  /** Default dropdown open state */
25
  defaultListboxOpen?: boolean;
26
  /** Default selected value(s) */
27
  defaultValue?: SelectValue<OptionValue, Multiple>;
28
  /** Whether select is disabled */
29
  disabled?: boolean;
30
  /** Function to serialize option values */
31
  getSerializedValue?: (option: string | OptionValue) => string;
32
  /** ID for the listbox element */
33
  listboxId?: string;
34
  /** Controlled dropdown open state */
35
  listboxOpen?: boolean;
36
  /** Whether multiple selection is allowed */
37
  multiple?: Multiple;
38
  /** Form input name */
39
  name?: string;
40
  /** Value change handler */
41
  onChange?: (event: React.MouseEvent | React.KeyboardEvent | React.FocusEvent | null, value: SelectValue<OptionValue, Multiple>) => void;
42
  /** Dropdown open state change handler */
43
  onListboxOpenChange?: (isOpen: boolean) => void;
44
  /** Placeholder content when no value selected */
45
  placeholder?: React.ReactNode;
46
  /** Whether select is required */
47
  required?: boolean;
48
  /** Current selected value(s) */
49
  value?: SelectValue<OptionValue, Multiple>;
50
  /** Props for customizing select slots */
51
  slotProps?: {
52
    root?: SlotComponentProps<SelectSlots["root"], {}, SelectOwnerState<OptionValue, Multiple>>;
53
    listbox?: SlotComponentProps<SelectSlots["listbox"], {}, SelectOwnerState<OptionValue, Multiple>>;
54
    popper?: SlotComponentProps<SelectSlots["popper"], {}, SelectOwnerState<OptionValue, Multiple>>;
55
  };
56
  /** Components used for select slots */
57
  slots?: SelectSlots;
58
  /** Select children (Option components) */
59
  children?: React.ReactNode;
60
}
61

62
interface SelectSlots {
63
  /** Root button element */
64
  root?: React.ElementType;
65
  /** Listbox popup element */
66
  listbox?: React.ElementType;
67
  /** Popper positioning element */
68
  popper?: React.ElementType;
69
}
70

71
type SelectValue<OptionValue, Multiple extends boolean> = 
72
  Multiple extends true 
73
    ? OptionValue[] 
74
    : OptionValue | null;
75

76
interface SelectOwnerState<OptionValue, Multiple extends boolean> {
77
  disabled: boolean;
78
  multiple: Multiple;
79
  open: boolean;
80
  value: SelectValue<OptionValue, Multiple>;
81
}
82
```
83

84
**Usage Examples:**
85

86
```typescript
87
import { Select, Option } from "@mui/base";
88

89
// Basic select
90
<Select defaultValue="apple">
91
  <Option value="apple">Apple</Option>
92
  <Option value="banana">Banana</Option>
93
  <Option value="cherry">Cherry</Option>
94
</Select>
95

96
// Multiple selection
97
<Select multiple defaultValue={["apple", "banana"]}>
98
  <Option value="apple">Apple</Option>
99
  <Option value="banana">Banana</Option>
100
  <Option value="cherry">Cherry</Option>
101
</Select>
102

103
// Controlled select with change handler
104
<Select 
105
  value={selectedValue}
106
  onChange={(event, newValue) => setSelectedValue(newValue)}
107
>
108
  <Option value="option1">Option 1</Option>
109
  <Option value="option2">Option 2</Option>
110
</Select>
111
```
112

113
### Option Component
114

115
Individual option within Select component with selection state management.
116

117
```typescript { .api }
118
/**
119
 * Individual option within Select component
120
 * @param props - Option properties including value and label
121
 * @returns Option element with selection state
122
 */
123
function Option<OptionValue>(
124
  props: OptionProps<OptionValue>
125
): JSX.Element;
126

127
interface OptionProps<OptionValue>
128
  extends PolymorphicProps<OptionTypeMap<OptionValue>, React.ElementType> {
129
  /** Option content */
130
  children?: React.ReactNode;
131
  /** Whether option is disabled */
132
  disabled?: boolean;
133
  /** Human-readable text representing the option */
134
  label?: string;
135
  /** Value associated with the option */
136
  value: OptionValue;
137
}
138

139
interface OptionOwnerState<OptionValue> {
140
  disabled: boolean;
141
  highlighted: boolean;
142
  index: number;
143
  selected: boolean;
144
  value: OptionValue;
145
}
146
```
147

148
### OptionGroup Component
149

150
Groups related options within Select component.
151

152
```typescript { .api }
153
/**
154
 * Groups related options within Select component
155
 * @param props - Option group properties including label and children
156
 * @returns Option group element with proper ARIA labeling
157
 */
158
function OptionGroup(props: OptionGroupProps): JSX.Element;
159

160
interface OptionGroupProps
161
  extends PolymorphicProps<OptionGroupTypeMap, React.ElementType> {
162
  /** Option group content (Option components) */
163
  children?: React.ReactNode;
164
  /** Whether all options in group are disabled */
165
  disabled?: boolean;
166
  /** Label for the option group */
167
  label?: React.ReactNode;
168
}
169
```
170

171
### Menu Components
172

173
#### Menu Container
174

175
```typescript { .api }
176
/**
177
 * Headless menu container component with keyboard navigation
178
 * @param props - Menu properties including anchor element and open state
179
 * @returns Menu element with proper accessibility
180
 */
181
function Menu<RootComponentType extends React.ElementType = "div">(
182
  props: MenuProps<RootComponentType>
183
): JSX.Element;
184

185
interface MenuProps<RootComponentType extends React.ElementType = "div">
186
  extends PolymorphicProps<MenuTypeMap, RootComponentType> {
187
  /** Ref for imperative menu actions */
188
  actions?: React.Ref<MenuActions>;
189
  /** Anchor element for menu positioning */
190
  anchor?: VirtualElement | (() => VirtualElement) | null;
191
  /** Menu content (MenuItem components) */
192
  children?: React.ReactNode;
193
  /** Default menu open state */
194
  defaultOpen?: boolean;
195
  /** ID for the listbox element */
196
  listboxId?: string;
197
  /** Open state change handler */
198
  onOpenChange?: (open: boolean) => void;
199
  /** Controlled menu open state */
200
  open?: boolean;
201
  /** Props for customizing menu slots */
202
  slotProps?: {
203
    root?: SlotComponentProps<MenuSlots["root"], {}, MenuOwnerState>;
204
    listbox?: SlotComponentProps<MenuSlots["listbox"], {}, MenuOwnerState>;
205
  };
206
  /** Components used for menu slots */
207
  slots?: MenuSlots;
208
}
209

210
interface MenuSlots {
211
  /** Root container element */
212
  root?: React.ElementType;
213
  /** Listbox element containing menu items */
214
  listbox?: React.ElementType;
215
}
216

217
interface MenuActions {
218
  /** Close the menu */
219
  close: () => void;
220
}
221
```
222

223
#### MenuButton Component
224

225
```typescript { .api }
226
/**
227
 * Button that triggers menu open/close state
228
 * @param props - Menu button properties including disabled state
229
 * @returns Button element that controls menu visibility
230
 */
231
function MenuButton<RootComponentType extends React.ElementType = "button">(
232
  props: MenuButtonProps<RootComponentType>
233
): JSX.Element;
234

235
interface MenuButtonProps<RootComponentType extends React.ElementType = "button">
236
  extends PolymorphicProps<MenuButtonTypeMap, RootComponentType> {
237
  /** Button content */
238
  children?: React.ReactNode;
239
  /** Whether button is disabled */
240
  disabled?: boolean;
241
  /** Whether button is focusable when disabled */
242
  focusableWhenDisabled?: boolean;
243
  /** Accessible label for the button */
244
  label?: string;
245
}
246
```
247

248
#### MenuItem Component
249

250
```typescript { .api }
251
/**
252
 * Individual menu item component with selection handling
253
 * @param props - Menu item properties including click handlers
254
 * @returns Menu item element with proper accessibility
255
 */
256
function MenuItem<RootComponentType extends React.ElementType = "li">(
257
  props: MenuItemProps<RootComponentType>
258
): JSX.Element;
259

260
interface MenuItemProps<RootComponentType extends React.ElementType = "li">
261
  extends PolymorphicProps<MenuItemTypeMap, RootComponentType> {
262
  /** Menu item content */
263
  children?: React.ReactNode;
264
  /** Whether to close menu on item click (default: true) */
265
  closeOnClick?: boolean;
266
  /** Whether menu item is disabled */
267
  disabled?: boolean;
268
  /** Menu item ID */
269
  id?: string;
270
  /** Accessible label for the menu item */
271
  label?: string;
272
  /** Click event handler */
273
  onClick?: React.MouseEventHandler<any>;
274
}
275
```
276

277
#### Dropdown Context
278

279
```typescript { .api }
280
/**
281
 * Context provider for dropdown state management
282
 * @param props - Dropdown properties including open state
283
 * @returns Context provider for dropdown state
284
 */
285
function Dropdown(props: DropdownProps): JSX.Element;
286

287
interface DropdownProps {
288
  /** Dropdown children components */
289
  children?: React.ReactNode;
290
  /** Default open state (default: false) */
291
  defaultOpen?: boolean;
292
  /** Open state change handler */
293
  onOpenChange?: (open: boolean, event?: Event) => void;
294
  /** Controlled open state */
295
  open?: boolean;
296
}
297
```
298

299
### Tab Components
300

301
#### Tabs Container
302

303
```typescript { .api }
304
/**
305
 * Tab container with selection state management and keyboard navigation
306
 * @param props - Tabs properties including value and orientation
307
 * @returns Tabs container with proper ARIA attributes
308
 */
309
function Tabs<RootComponentType extends React.ElementType = "div">(
310
  props: TabsProps<RootComponentType>
311
): JSX.Element;
312

313
interface TabsProps<RootComponentType extends React.ElementType = "div">
314
  extends PolymorphicProps<TabsTypeMap, RootComponentType> {
315
  /** Tab content (TabsList and TabPanel components) */
316
  children?: React.ReactNode;
317
  /** Default selected tab value */
318
  defaultValue?: string | number | null;
319
  /** Text direction affecting keyboard navigation */
320
  direction?: 'ltr' | 'rtl';
321
  /** Selection change handler */
322
  onChange?: (event: React.SyntheticEvent, value: string | number) => void;
323
  /** Tab list orientation (default: 'horizontal') */
324
  orientation?: 'horizontal' | 'vertical';
325
  /** Whether selection follows focus (default: false) */
326
  selectionFollowsFocus?: boolean;
327
  /** Currently selected tab value */
328
  value?: string | number | null;
329
}
330
```
331

332
#### TabsList Component
333

334
```typescript { .api }
335
/**
336
 * Container for tab buttons with keyboard navigation
337
 * @param props - Tabs list properties
338
 * @returns Tab list element with arrow key navigation
339
 */
340
function TabsList<RootComponentType extends React.ElementType = "div">(
341
  props: TabsListProps<RootComponentType>
342
): JSX.Element;
343

344
interface TabsListProps<RootComponentType extends React.ElementType = "div">
345
  extends PolymorphicProps<TabsListTypeMap, RootComponentType> {
346
  /** Tab buttons (Tab components) */
347
  children?: React.ReactNode;
348
}
349
```
350

351
#### Tab Component
352

353
```typescript { .api }
354
/**
355
 * Individual tab button component
356
 * @param props - Tab properties including value and disabled state
357
 * @returns Tab button element with selection state
358
 */
359
function Tab<RootComponentType extends React.ElementType = "button">(
360
  props: TabProps<RootComponentType>
361
): JSX.Element;
362

363
interface TabProps<RootComponentType extends React.ElementType = "button">
364
  extends PolymorphicProps<TabTypeMap, RootComponentType> {
365
  /** Ref for imperative tab actions */
366
  action?: React.Ref<TabActions>;
367
  /** Tab content */
368
  children?: React.ReactNode;
369
  /** Whether tab is disabled */
370
  disabled?: boolean;
371
  /** Selection change handler */
372
  onChange?: (event: React.SyntheticEvent, value: string | number) => void;
373
  /** Tab identifier value */
374
  value?: string | number;
375
}
376

377
interface TabActions {
378
  /** Focus the tab */
379
  focus(): void;
380
}
381
```
382

383
#### TabPanel Component
384

385
```typescript { .api }
386
/**
387
 * Content panel associated with tab
388
 * @param props - Tab panel properties including value and keepMounted
389
 * @returns Tab panel element with conditional visibility
390
 */
391
function TabPanel<RootComponentType extends React.ElementType = "div">(
392
  props: TabPanelProps<RootComponentType>
393
): JSX.Element;
394

395
interface TabPanelProps<RootComponentType extends React.ElementType = "div">
396
  extends PolymorphicProps<TabPanelTypeMap, RootComponentType> {
397
  /** Panel content */
398
  children?: React.ReactNode;
399
  /** Whether to keep content mounted when not active */
400
  keepMounted?: boolean;
401
  /** Panel identifier value matching tab value */
402
  value: string | number;
403
}
404
```
405

406
**Usage Examples:**
407

408
```typescript
409
import { Tabs, TabsList, Tab, TabPanel } from "@mui/base";
410

411
// Basic tabs
412
<Tabs defaultValue="tab1">
413
  <TabsList>
414
    <Tab value="tab1">Tab 1</Tab>
415
    <Tab value="tab2">Tab 2</Tab>
416
    <Tab value="tab3">Tab 3</Tab>
417
  </TabsList>
418
  
419
  <TabPanel value="tab1">Content for Tab 1</TabPanel>
420
  <TabPanel value="tab2">Content for Tab 2</TabPanel>
421
  <TabPanel value="tab3">Content for Tab 3</TabPanel>
422
</Tabs>
423

424
// Vertical tabs with controlled selection
425
<Tabs 
426
  orientation="vertical"
427
  value={activeTab}
428
  onChange={(event, newValue) => setActiveTab(newValue)}
429
>
430
  <TabsList>
431
    <Tab value="profile">Profile</Tab>
432
    <Tab value="settings">Settings</Tab>
433
    <Tab value="billing">Billing</Tab>
434
  </TabsList>
435
  
436
  <TabPanel value="profile">Profile settings...</TabPanel>
437
  <TabPanel value="settings">General settings...</TabPanel>
438
  <TabPanel value="billing">Billing information...</TabPanel>
439
</Tabs>
440
```
441

442
## Related Hooks
443

444
```typescript { .api }
445
// Select behavior hook
446
function useSelect<OptionValue, Multiple extends boolean>(
447
  props: UseSelectParameters<OptionValue, Multiple>
448
): UseSelectReturnValue<OptionValue, Multiple>;
449

450
// Option behavior hook
451
function useOption<OptionValue>(
452
  props: UseOptionParameters<OptionValue>
453
): UseOptionReturnValue;
454

455
// Autocomplete functionality hook
456
function useAutocomplete<Value, Multiple, DisableClearable, FreeSolo>(
457
  props: UseAutocompleteProps<Value, Multiple, DisableClearable, FreeSolo>
458
): UseAutocompleteReturnValue<Value, Multiple, DisableClearable, FreeSolo>;
459

460
// Menu behavior hooks
461
function useMenu(props: UseMenuParameters): UseMenuReturnValue;
462
function useMenuButton(props: UseMenuButtonParameters): UseMenuButtonReturnValue;
463
function useMenuItem(props: UseMenuItemParameters): UseMenuItemReturnValue;
464

465
// Dropdown behavior hook
466
function useDropdown(props: UseDropdownParameters): UseDropdownReturnValue;
467

468
// Tab behavior hooks
469
function useTabs(props: UseTabsParameters): UseTabsReturnValue;
470
function useTabsList(props: UseTabsListParameters): UseTabsListReturnValue;
471
function useTab(props: UseTabParameters): UseTabReturnValue;
472
function useTabPanel(props: UseTabPanelParameters): UseTabPanelReturnValue;
473
```