0
# React Hooks
1

2
Modern React hooks for component state management, lifecycle handling, and performance optimization. These hooks are essential for building custom components with proper React patterns.
3

4
## Capabilities
5

6
### Controlled State Management
7

8
#### useControlled
9

10
Hook for managing controlled/uncontrolled component state with development warnings.
11

12
```typescript { .api }
13
/**
14
 * Hook for managing controlled/uncontrolled component state
15
 * @param props - Configuration object for controlled state
16
 * @returns Tuple of [value, setValue] for state management
17
 */
18
function unstable_useControlled<T = unknown>(
19
  props: UseControlledProps<T>
20
): [T, React.Dispatch<React.SetStateAction<T | undefined>>];
21

22
interface UseControlledProps<T = unknown> {
23
  /** Holds the component value when it's controlled */
24
  controlled: T | undefined;
25
  /** The default value when uncontrolled */
26
  default: T | undefined;
27
  /** The component name displayed in warnings */
28
  name: string;
29
  /** The name of the state variable displayed in warnings */
30
  state?: string;
31
}
32
```
33

34
**Usage Example:**
35

36
```typescript
37
import { unstable_useControlled as useControlled } from '@mui/utils';
38

39
function CustomInput({ value, defaultValue, onChange }) {
40
  const [inputValue, setInputValue] = useControlled({
41
    controlled: value,
42
    default: defaultValue,
43
    name: 'CustomInput',
44
    state: 'value'
45
  });
46

47
  const handleChange = React.useCallback((event) => {
48
    setInputValue(event.target.value);
49
    onChange?.(event);
50
  }, [onChange, setInputValue]);
51

52
  return <input value={inputValue} onChange={handleChange} />;
53
}
54
```
55

56
### Event Handling
57

58
#### useEventCallback
59

60
Creates a stable callback that doesn't change between renders but always calls the latest version of the provided function.
61

62
```typescript { .api }
63
/**
64
 * Creates a stable callback that doesn't change between renders
65
 * @param fn - Function to wrap in stable callback
66
 * @returns Stable callback function
67
 */
68
function unstable_useEventCallback<Args, Return>(
69
  fn: (...args: Args[]) => Return
70
): (...args: Args[]) => Return;
71
```
72

73
**Usage Example:**
74

75
```typescript
76
import { unstable_useEventCallback as useEventCallback } from '@mui/utils';
77

78
function MyComponent({ onSubmit, data }) {
79
  const handleSubmit = useEventCallback((event) => {
80
    event.preventDefault();
81
    onSubmit(data); // Always uses latest data value
82
  });
83

84
  return <form onSubmit={handleSubmit}>...</form>;
85
}
86
```
87

88
### Ref Management
89

90
#### useForkRef
91

92
Merges multiple refs into a single memoized callback ref, useful when you need to apply multiple refs to the same element.
93

94
```typescript { .api }
95
/**
96
 * Merges refs into a single memoized callback ref or null
97
 * @param refs - Array of refs to merge
98
 * @returns Combined ref callback or null
99
 */
100
function unstable_useForkRef<Instance>(
101
  ...refs: Array<React.Ref<Instance> | undefined>
102
): React.RefCallback<Instance> | null;
103
```
104

105
**Usage Example:**
106

107
```typescript
108
import { unstable_useForkRef as useForkRef } from '@mui/utils';
109

110
const MyComponent = React.forwardRef<HTMLDivElement, MyProps>((props, ref) => {
111
  const internalRef = React.useRef<HTMLDivElement>(null);
112
  const anotherRef = React.useRef<HTMLDivElement>(null);
113
  const combinedRef = useForkRef(ref, internalRef, anotherRef);
114

115
  return <div ref={combinedRef}>Content</div>;
116
});
117
```
118

119
#### useLazyRef
120

121
Provides lazy initialization of refs, useful for expensive initialization that should only happen once.
122

123
```typescript { .api }
124
/**
125
 * Provides lazy initialization of refs
126
 * @param init - Initialization function called once
127
 * @returns Mutable ref object with initialized value
128
 */
129
function unstable_useLazyRef<T>(init: () => T): React.MutableRefObject<T>;
130
```
131

132
### Lifecycle Hooks
133

134
#### useEnhancedEffect
135

136
Uses `useLayoutEffect` on the client and `useEffect` on the server for better SSR compatibility.
137

138
```typescript { .api }
139
/**
140
 * Uses useLayoutEffect on client, useEffect on server
141
 * @param effect - Effect function to execute
142
 * @param deps - Optional dependency list
143
 */
144
function unstable_useEnhancedEffect(
145
  effect: React.EffectCallback, 
146
  deps?: React.DependencyList
147
): void;
148
```
149

150
#### useOnMount
151

152
Runs an effect only on component mount, ignoring dependency changes.
153

154
```typescript { .api }
155
/**
156
 * Runs effect only on component mount
157
 * @param fn - Function to execute on mount
158
 */
159
function unstable_useOnMount(fn: () => void): void;
160
```
161

162
### Focus Management
163

164
#### useIsFocusVisible
165

166
Hook for managing focus-visible behavior, determining when focus should be visually indicated.
167

168
```typescript { .api }
169
/**
170
 * Hook for focus-visible behavior management
171
 * @returns Object with focus-visible utilities
172
 */
173
function unstable_useIsFocusVisible(): {
174
  isFocusVisibleRef: React.MutableRefObject<boolean>;
175
  onFocus: (event: React.FocusEvent) => void;
176
  onBlur: () => void;
177
  ref: React.RefCallback<Element>;
178
};
179
```
180

181
### Unique Identification
182

183
#### useId
184

185
Generates stable unique IDs for accessibility, with React 18+ compatibility.
186

187
```typescript { .api }
188
/**
189
 * Generates stable unique IDs for accessibility
190
 * @param idOverride - Optional ID override
191
 * @returns Stable unique ID string
192
 */
193
function unstable_useId(idOverride?: string): string;
194
```
195

196
### Previous Value Tracking
197

198
#### usePreviousProps
199

200
Returns the previous value from the previous render.
201

202
```typescript { .api }
203
/**
204
 * Returns previous value from previous render
205
 * @param value - Current value to track
206
 * @returns Previous value or undefined on first render
207
 */
208
function usePreviousProps<T>(value: T): T | undefined;
209
```
210

211
### Timer Management
212

213
#### useTimeout
214

215
Hook for managing timeouts with start and clear functionality.
216

217
```typescript { .api }
218
/**
219
 * Hook for managing timeouts
220
 * @returns Object with timeout control methods
221
 */
222
function unstable_useTimeout(): {
223
  start: (delay: number, callback: () => void) => void;
224
  clear: () => void;
225
};
226

227
type Timeout = ReturnType<typeof unstable_useTimeout>;
228
```
229

230
### Slot Management
231

232
#### useSlotProps
233

234
Hook for managing slot component props with advanced prop resolution and owner state integration.
235

236
```typescript { .api }
237
/**
238
 * Hook for managing slot component props
239
 * @param parameters - Slot props configuration
240
 * @returns Resolved slot props
241
 */
242
function unstable_useSlotProps<TSlotComponent, TSlotState, TSlotOwnerState>(
243
  parameters: UseSlotPropsParameters<TSlotComponent, TSlotState, TSlotOwnerState>
244
): UseSlotPropsResult<TSlotComponent>;
245

246
interface UseSlotPropsParameters<TSlotComponent, TSlotState, TSlotOwnerState> {
247
  elementType: TSlotComponent;
248
  externalSlotProps: any;
249
  ownerState: TSlotOwnerState;
250
  skipResolvingSlotProps?: boolean;
251
  additionalProps?: any;
252
  internalSlotProps?: any;
253
}
254

255
interface UseSlotPropsResult<TSlotComponent> {
256
  props: React.ComponentPropsWithRef<TSlotComponent>;
257
  internalRef: React.Ref<any>;
258
}
259
```