0
# MUI Base
1

2
MUI Base is a library of headless (unstyled) React components and low-level hooks that provides complete control over your app's CSS and accessibility features. It offers foundational UI components like buttons, inputs, modals, menus, and navigation elements without any default styling, allowing for maximum customization while maintaining accessibility standards and semantic HTML structure.
3

4
## Package Information
5

6
- **Package Name**: @mui/base
7
- **Package Type**: npm
8
- **Language**: TypeScript/JavaScript
9
- **Installation**: `npm install @mui/base`
10

11
## Core Imports
12

13
```typescript
14
import { Button, Input, Select, Menu, Modal } from "@mui/base";
15
```
16

17
For specific components:
18

19
```typescript
20
import { Button } from "@mui/base/Button";
21
import { useButton } from "@mui/base/useButton";
22
```
23

24
CommonJS:
25

26
```javascript
27
const { Button, Input, Select } = require("@mui/base");
28
```
29

30
## Basic Usage
31

32
```typescript
33
import { Button, Input, FormControl } from "@mui/base";
34

35
function App() {
36
  return (
37
    <div>
38
      {/* Headless button - bring your own styles */}
39
      <Button className="my-button" onClick={() => alert("Clicked!")}>
40
        Click me
41
      </Button>
42

43
      {/* Form control with input */}
44
      <FormControl>
45
        <Input 
46
          placeholder="Enter text"
47
          className="my-input"
48
          slotProps={{
49
            input: { className: "my-input-element" }
50
          }}
51
        />
52
      </FormControl>
53
    </div>
54
  );
55
}
56
```
57

58
## Architecture
59

60
MUI Base is built around several key architectural patterns:
61

62
- **Headless Components**: No default styling, complete CSS control
63
- **Slot-based Architecture**: Each component exposes customizable "slots" (sub-elements) via the `slots` and `slotProps` props, with advanced prop merging via `mergeSlotProps` for complete customization control
64
- **Polymorphic Components**: Components can render as different HTML elements via the `component` prop
65
- **Hook-based Logic**: Each component has a corresponding hook (e.g., `useButton`) that can be used standalone
66
- **Accessibility First**: Built-in ARIA attributes, keyboard navigation, and focus management
67
- **TypeScript Integration**: Full type safety with generic support for polymorphic behavior
68
- **CSS Class System**: Each component exports a `*Classes` object (e.g., `buttonClasses`) for consistent styling with utility class generation
69

70
## Capabilities
71

72
### Form Controls
73

74
Core form elements including buttons, inputs, switches, and sliders with full accessibility support and customizable styling.
75

76
```typescript { .api }
77
// Button component with polymorphic support
78
function Button<RootComponentType extends React.ElementType = "button">(
79
  props: ButtonProps<RootComponentType>
80
): JSX.Element;
81

82
// Input component with form control integration
83
function Input<RootComponentType extends React.ElementType = "div">(
84
  props: InputProps<RootComponentType>
85
): JSX.Element;
86

87
// Switch toggle component
88
function Switch<RootComponentType extends React.ElementType = "span">(
89
  props: SwitchProps<RootComponentType>
90
): JSX.Element;
91
```
92

93
[Form Controls](./form-controls.md)
94

95
### Selection & Navigation
96

97
Components for user selection including dropdowns, menus, and tabs with keyboard navigation and accessibility features.
98

99
```typescript { .api }
100
// Select dropdown component
101
function Select<OptionValue, Multiple extends boolean = false>(
102
  props: SelectProps<OptionValue, Multiple>
103
): JSX.Element;
104

105
// Menu component for contextual actions
106
function Menu<RootComponentType extends React.ElementType = "div">(
107
  props: MenuProps<RootComponentType>
108
): JSX.Element;
109

110
// Tab navigation components
111
function Tabs<RootComponentType extends React.ElementType = "div">(
112
  props: TabsProps<RootComponentType>
113
): JSX.Element;
114
```
115

116
[Selection & Navigation](./selection-navigation.md)
117

118
### Layout & Positioning
119

120
Components for popups, modals, overlays, and transitions with advanced positioning using Floating UI.
121

122
```typescript { .api }
123
// Modal dialog component
124
function Modal(props: ModalProps): JSX.Element;
125

126
// Floating popup component
127
function Unstable_Popup(props: PopupProps): JSX.Element;
128

129
// Portal component for rendering outside DOM tree
130
function Portal(props: PortalProps): JSX.Element;
131

132
// CSS transition wrapper component
133
function CssTransition(props: CssTransitionProps): JSX.Element;
134

135
// CSS animation wrapper component
136
function CssAnimation(props: CssAnimationProps): JSX.Element;
137
```
138

139
[Layout & Positioning](./layout-positioning.md)
140

141
### Data Display
142

143
Components for displaying data including tables, badges, and notifications.
144

145
```typescript { .api }
146
// Badge component for status indicators
147
function Badge<RootComponentType extends React.ElementType = "span">(
148
  props: BadgeProps<RootComponentType>
149
): JSX.Element;
150

151
// Table pagination controls
152
function TablePagination<RootComponentType extends React.ElementType = "div">(
153
  props: TablePaginationProps<RootComponentType>
154
): JSX.Element;
155

156
// Snackbar notification component
157
function Snackbar<RootComponentType extends React.ElementType = "div">(
158
  props: SnackbarProps<RootComponentType>
159
): JSX.Element;
160
```
161

162
[Data Display](./data-display.md)
163

164
### Hooks & Utilities
165

166
React hooks and utility functions for building custom components with MUI Base behavior, including slot management and CSS class composition.
167

168
```typescript { .api }
169
// Button behavior hook
170
function useButton(parameters: UseButtonParameters): UseButtonReturnValue;
171

172
// Autocomplete functionality hook
173
function useAutocomplete<Value, Multiple, DisableClearable, FreeSolo>(
174
  props: UseAutocompleteProps<Value, Multiple, DisableClearable, FreeSolo>
175
): UseAutocompleteReturnValue<Value, Multiple, DisableClearable, FreeSolo>;
176

177
// CSS class generation utility
178
function generateUtilityClass(componentName: string, slot: string): string;
179

180
// Slot prop merging utility
181
function mergeSlotProps<SlotProps, ExternalForwardedProps, ExternalSlotProps, AdditionalProps>(
182
  parameters: MergeSlotPropsParameters<SlotProps, ExternalForwardedProps, ExternalSlotProps, AdditionalProps>
183
): MergeSlotPropsResult<SlotProps, ExternalForwardedProps, ExternalSlotProps, AdditionalProps>;
184

185
// CSS class composition utility
186
declare const unstable_composeClasses: <T extends string>(
187
  slots: Record<T, readonly string[]>,
188
  getUtilityClass: (slot: string) => string,
189
  classes?: Partial<Record<T, string>>
190
) => Record<T, string>;
191
```
192

193
[Hooks & Utilities](./hooks-utilities.md)
194

195
## Core Types
196

197
```typescript { .api }
198
// Polymorphic component support
199
interface PolymorphicProps<TypeMap extends PolymorphicTypeMap, RootComponentType extends React.ElementType> {
200
  component?: RootComponentType;
201
}
202

203
// Slot-based component props
204
interface SlotComponentProps<
205
  ElementType extends React.ElementType,
206
  SlotPropsOverrides,
207
  OwnerState
208
> {
209
  className?: string;
210
  children?: React.ReactNode;
211
}
212

213
// Common slot props pattern
214
interface ComponentSlots {
215
  root?: React.ElementType;
216
  [key: string]: React.ElementType | undefined;
217
}
218

219
interface ComponentSlotProps<Slots extends ComponentSlots> {
220
  [K in keyof Slots]?: SlotComponentProps<
221
    NonNullable<Slots[K]>,
222
    {},
223
    any
224
  >;
225
}
226
```