0
# MUI Utils
1

2
MUI Utils is a comprehensive TypeScript utility library providing 53+ functions specifically designed for React component development. It serves as the foundational utility layer for the Material-UI (MUI) ecosystem and can be used independently in any React application requiring robust utility functions.
3

4
## Package Information
5

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

11
## Core Imports
12

13
```typescript
14
import { 
15
  deepmerge, 
16
  useControlled, 
17
  generateUtilityClass,
18
  clamp,
19
  setRef 
20
} from '@mui/utils';
21
```
22

23
For CommonJS:
24

25
```javascript
26
const { 
27
  deepmerge, 
28
  useControlled, 
29
  generateUtilityClass,
30
  clamp,
31
  setRef 
32
} = require('@mui/utils');
33
```
34

35
## Basic Usage
36

37
```typescript
38
import { 
39
  deepmerge, 
40
  unstable_useEventCallback as useEventCallback,
41
  unstable_generateUtilityClass as generateUtilityClass,
42
  clamp 
43
} from '@mui/utils';
44

45
// Deep merge objects with React element handling
46
const merged = deepmerge(
47
  { styles: { color: 'blue' }, props: { disabled: true } },
48
  { styles: { fontSize: 16 }, props: { variant: 'contained' } }
49
);
50

51
// Stable event callback hook
52
const handleClick = useEventCallback((event) => {
53
  console.log('Button clicked:', event.target);
54
});
55

56
// Generate CSS utility class names
57
const buttonClass = generateUtilityClass('MuiButton', 'root');
58
// Result: 'MuiButton-root'
59

60
// Clamp numeric values
61
const boundedValue = clamp(150, 0, 100); // Result: 100
62
```
63

64
## Architecture
65

66
MUI Utils is organized around several key architectural patterns:
67

68
- **Individual Exports**: Each utility is independently importable for optimal tree-shaking
69
- **TypeScript-First**: Complete type safety with generic type preservation
70
- **React-Optimized**: Utilities designed specifically for React patterns and lifecycle
71
- **Stability Levels**: APIs marked as `unstable_` are stable in implementation but may change in future versions
72
- **Cross-Environment**: Many utilities handle both client-side and server-side rendering
73
- **PropType Integration**: Comprehensive development-time validation utilities
74

75
## Capabilities
76

77
### React Hooks
78

79
Modern React hooks for component state management, lifecycle handling, and performance optimization. Essential for building custom components with proper React patterns.
80

81
```typescript { .api }
82
function unstable_useControlled<T>(
83
  props: UseControlledProps<T>
84
): [T, React.Dispatch<React.SetStateAction<T | undefined>>];
85

86
function unstable_useEventCallback<Args, Return>(
87
  fn: (...args: Args[]) => Return
88
): (...args: Args[]) => Return;
89

90
function unstable_useForkRef<Instance>(
91
  ...refs: Array<React.Ref<Instance> | undefined>
92
): React.RefCallback<Instance> | null;
93
```
94

95
[React Hooks](./react-hooks.md)
96

97
### PropType Validators
98

99
Development-time validation utilities for React component props, providing enhanced debugging and type checking in development mode.
100

101
```typescript { .api }
102
function chainPropTypes(
103
  validator: React.Validator<any>, 
104
  ...validators: React.Validator<any>[]
105
): React.Validator<any>;
106

107
function exactProp(propTypes: Record<string, any>): Record<string, any>;
108

109
const HTMLElementType: React.Validator<any>;
110
const elementAcceptingRef: React.Validator<any>;
111
const refType: React.Validator<any>;
112
```
113

114
[PropType Validators](./proptype-validators.md)
115

116
### Component Utilities
117

118
Essential utilities for React component manipulation, ref handling, and component introspection.
119

120
```typescript { .api }
121
function getDisplayName(Component: React.ComponentType<any>): string;
122

123
function getValidReactChildren(children: React.ReactNode): React.ReactElement[];
124

125
function unstable_setRef<T>(
126
  ref: React.Ref<T> | undefined, 
127
  value: T | null
128
): void;
129

130
function unstable_getReactElementRef(
131
  element: React.ReactElement
132
): React.Ref<any> | null;
133
```
134

135
[Component Utilities](./component-utilities.md)
136

137
### Object and Function Utilities
138

139
General-purpose utilities for object manipulation, function composition, and data processing.
140

141
```typescript { .api }
142
function deepmerge<T>(
143
  target: T, 
144
  source: unknown, 
145
  options?: DeepmergeOptions
146
): T;
147

148
function clamp(value: number, min: number, max: number): number;
149

150
function unstable_debounce<T extends (...args: any[]) => any>(
151
  func: T, 
152
  wait?: number, 
153
  options?: DebounceOptions
154
): T & { clear: () => void; flush: () => void };
155
```
156

157
[Object and Function Utilities](./object-function-utilities.md)
158

159
### CSS Class and Style Utilities
160

161
Utilities for CSS class name generation, composition, and styling management in component libraries.
162

163
```typescript { .api }
164
function unstable_generateUtilityClass(
165
  componentName: string, 
166
  slot: string, 
167
  globalStatePrefix?: string
168
): string;
169

170
function unstable_composeClasses<SlotKey extends string>(
171
  slots: Record<SlotKey, string | false | null | undefined>,
172
  getUtilityClass: (slot: SlotKey) => string,
173
  classes?: Partial<Record<SlotKey, string>>
174
): Record<SlotKey, string>;
175

176
const visuallyHidden: React.CSSProperties;
177
```
178

179
[CSS Class and Style Utilities](./css-utilities.md)
180

181
### DOM Utilities
182

183
Browser and DOM manipulation utilities for cross-platform React applications.
184

185
```typescript { .api }
186
function unstable_ownerDocument(node?: Node | null): Document;
187

188
function unstable_ownerWindow(node?: Node | null): Window;
189

190
function unstable_getScrollbarSize(doc?: Document): number;
191

192
function unstable_isFocusVisible(element: Element): boolean;
193
```
194

195
[DOM Utilities](./dom-utilities.md)
196

197
### String and Text Utilities
198

199
Text manipulation and formatting utilities for user interface content.
200

201
```typescript { .api }
202
function unstable_capitalize(string: string): string;
203

204
function formatMuiErrorMessage(code: number, ...args: any[]): string;
205
```
206

207
[String and Text Utilities](./string-utilities.md)
208

209
### Slot and Props Utilities
210

211
Advanced prop management utilities for component slot patterns and dynamic prop resolution.
212

213
```typescript { .api }
214
function unstable_useSlotProps<TSlotComponent, TSlotState, TSlotOwnerState>(
215
  parameters: UseSlotPropsParameters<TSlotComponent, TSlotState, TSlotOwnerState>
216
): UseSlotPropsResult<TSlotComponent>;
217
```
218

219
[Slot and Props Utilities](./slot-props-utilities.md)
220

221
## Types
222

223
```typescript { .api }
224
interface UseControlledProps<T = unknown> {
225
  controlled: T | undefined;
226
  default: T | undefined;
227
  name: string;
228
  state?: string;
229
}
230

231
interface DeepmergeOptions {
232
  clone?: boolean;
233
}
234

235
type EventHandlers = Record<string, React.EventHandler<any>>;
236

237
type WithOptionalOwnerState<Props extends { ownerState: unknown }> = Omit<
238
  Props,
239
  'ownerState'
240
> & Partial<Pick<Props, 'ownerState'>>;
241

242
type SlotComponentProps<TSlotComponent extends React.ElementType, TOverrides, TOwnerState> =
243
  | (Partial<React.ComponentPropsWithRef<TSlotComponent>> & TOverrides)
244
  | ((ownerState: TOwnerState) => Partial<React.ComponentPropsWithRef<TSlotComponent>> & TOverrides);
245
```