0
# Hooks & Utilities
1

2
React hooks for state management, responsive design, accessibility, and utility functions for enhanced development experience.
3

4
## Capabilities
5

6
### State Management Hooks
7

8
#### useDisclose Hook
9

10
Hook for managing disclosure states (open/close) for modals, drawers, and other toggleable components.
11

12
```typescript { .api }
13
/**
14
 * Hook for managing disclosure state (open/close)
15
 * @param defaultIsOpen - Initial open state
16
 * @returns Disclosure state and control functions
17
 */
18
function useDisclose(defaultIsOpen?: boolean): DisclosureReturn;
19

20
interface DisclosureReturn {
21
  isOpen: boolean;
22
  onClose: () => void;
23
  onOpen: () => void;
24
  onToggle: () => void;
25
}
26
```
27

28
**Usage Example:**
29

30
```typescript
31
import { useDisclose, Modal, Button } from "native-base";
32

33
function DisclosureExample() {
34
  const { isOpen, onOpen, onClose } = useDisclose();
35
  
36
  return (
37
    <>
38
      <Button onPress={onOpen}>Open Modal</Button>
39
      <Modal isOpen={isOpen} onClose={onClose}>
40
        <Modal.Content>
41
          <Modal.Header>Modal Title</Modal.Header>
42
          <Modal.Body>Modal content</Modal.Body>
43
        </Modal.Content>
44
      </Modal>
45
    </>
46
  );
47
}
48
```
49

50
#### useControllableState Hook
51

52
Hook for managing controllable component state patterns.
53

54
```typescript { .api }
55
/**
56
 * Hook for managing controllable state patterns
57
 * @param props - Controllable state configuration
58
 * @returns State value and setter function
59
 */
60
function useControllableState<T>(props: ControllableStateProps<T>): [T, (value: T) => void];
61

62
/**
63
 * Hook for managing controllable prop patterns
64
 * @param props - Controllable prop configuration
65
 * @returns Resolved prop value
66
 */
67
function useControllableProp<T>(props: ControllablePropProps<T>): T;
68

69
interface ControllableStateProps<T> {
70
  value?: T;
71
  defaultValue?: T;
72
  onChange?: (value: T) => void;
73
}
74

75
interface ControllablePropProps<T> {
76
  value?: T;
77
  defaultValue?: T;
78
  onChange?: (value: T) => void;
79
}
80
```
81

82
### Responsive Design Hooks
83

84
#### useBreakpointValue Hook
85

86
Hook for selecting values based on current screen breakpoint.
87

88
```typescript { .api }
89
/**
90
 * Hook for selecting values based on current breakpoint
91
 * @param values - Responsive value object or array
92
 * @returns Value for current breakpoint
93
 */
94
function useBreakpointValue<T>(values: ResponsiveValue<T>): T;
95

96
type ResponsiveValue<T> = 
97
  | T 
98
  | T[] 
99
  | { 
100
      base?: T; 
101
      sm?: T; 
102
      md?: T; 
103
      lg?: T; 
104
      xl?: T; 
105
      '2xl'?: T; 
106
    };
107
```
108

109
**Usage Example:**
110

111
```typescript
112
import { useBreakpointValue, Text } from "native-base";
113

114
function ResponsiveText() {
115
  const fontSize = useBreakpointValue({
116
    base: "sm",
117
    sm: "md",
118
    md: "lg",
119
    lg: "xl"
120
  });
121
  
122
  return <Text fontSize={fontSize}>Responsive text size</Text>;
123
}
124
```
125

126
#### useMediaQuery Hook
127

128
Hook for media query matching and responsive behavior.
129

130
```typescript { .api }
131
/**
132
 * Hook for media query matching
133
 * @param query - Media query string or array of queries
134
 * @returns Array of boolean values indicating query matches
135
 */
136
function useMediaQuery(query: string | string[]): boolean[];
137
```
138

139
**Usage Example:**
140

141
```typescript
142
import { useMediaQuery, Box, Text } from "native-base";
143

144
function MediaQueryExample() {
145
  const [isLargeScreen, isMediumScreen] = useMediaQuery([
146
    "(min-width: 768px)",
147
    "(min-width: 480px) and (max-width: 767px)"
148
  ]);
149
  
150
  return (
151
    <Box>
152
      {isLargeScreen && <Text>Large screen content</Text>}
153
      {isMediumScreen && <Text>Medium screen content</Text>}
154
    </Box>
155
  );
156
}
157
```
158

159
### Accessibility Hooks
160

161
#### useScreenReaderEnabled Hook
162

163
Hook for detecting screen reader availability.
164

165
```typescript { .api }
166
/**
167
 * Hook for detecting if screen reader is enabled
168
 * @returns Boolean indicating screen reader status
169
 */
170
function useScreenReaderEnabled(): boolean;
171
```
172

173
#### useContrastText Hook
174

175
Hook for calculating accessible contrast text colors.
176

177
```typescript { .api }
178
/**
179
 * Hook for calculating accessible contrast text color
180
 * @param backgroundColor - Background color to contrast against
181
 * @returns Accessible text color (light or dark)
182
 */
183
function useContrastText(backgroundColor: string): string;
184
```
185

186
### Platform & Environment Hooks
187

188
#### useSafeArea Hook
189

190
Hook for handling safe area insets on devices with notches or rounded corners.
191

192
```typescript { .api }
193
/**
194
 * Hook for accessing safe area insets
195
 * @returns Safe area inset values
196
 */
197
function useSafeArea(): SafeAreaReturn;
198

199
interface SafeAreaReturn {
200
  top: number;
201
  right: number;
202
  bottom: number;
203
  left: number;
204
}
205
```
206

207
#### useKeyboardBottomInset Hook
208

209
Hook for handling keyboard appearance and adjusting layout.
210

211
```typescript { .api }
212
/**
213
 * Hook for keyboard bottom inset handling
214
 * @returns Keyboard bottom inset value
215
 */
216
function useKeyboardBottomInset(): number;
217
```
218

219
#### useLayout Hook
220

221
Hook for measuring component layout dimensions.
222

223
```typescript { .api }
224
/**
225
 * Hook for measuring component layout
226
 * @returns Layout measurement utilities
227
 */
228
function useLayout(): LayoutReturn;
229

230
interface LayoutReturn {
231
  onLayout: (event: any) => void;
232
  layout: {
233
    x: number;
234
    y: number;
235
    width: number;
236
    height: number;
237
  };
238
}
239
```
240

241
### Clipboard Utilities
242

243
#### useClipboard Hook
244

245
Hook for clipboard read/write operations.
246

247
```typescript { .api }
248
/**
249
 * Hook for clipboard operations
250
 * @param value - Value to copy to clipboard
251
 * @param timeout - Reset timeout in milliseconds
252
 * @returns Clipboard utilities and state
253
 */
254
function useClipboard(value: string, timeout?: number): ClipboardReturn;
255

256
interface ClipboardReturn {
257
  value: string;
258
  onCopy: () => void;
259
  hasCopied: boolean;
260
}
261
```
262

263
**Usage Example:**
264

265
```typescript
266
import { useClipboard, Button, Text, HStack } from "native-base";
267

268
function ClipboardExample() {
269
  const { onCopy, hasCopied } = useClipboard("https://example.com");
270
  
271
  return (
272
    <HStack space={2} alignItems="center">
273
      <Text>https://example.com</Text>
274
      <Button onPress={onCopy}>
275
        {hasCopied ? "Copied!" : "Copy"}
276
      </Button>
277
    </HStack>
278
  );
279
}
280
```
281

282
### Styling Utilities
283

284
#### useSx Hook
285

286
Hook for applying styled system props with enhanced capabilities.
287

288
```typescript { .api }
289
/**
290
 * Hook for applying styled system properties
291
 * @param sx - Style object with theme-aware properties
292
 * @returns Resolved style properties
293
 */
294
function useSx(sx: SxProps): any;
295

296
interface SxProps extends StyledProps {
297
  [key: string]: any;
298
}
299
```
300

301
#### useStyledSystemPropsResolver Hook
302

303
Hook for resolving styled system props with theme integration.
304

305
```typescript { .api }
306
/**
307
 * Hook for resolving styled system props
308
 * @param props - Props object to resolve
309
 * @returns Resolved styled props
310
 */
311
function useStyledSystemPropsResolver(props: any): any;
312
```
313

314
### Keyboard Management
315

316
#### useKeyboardDismissable Hook
317

318
Hook for managing keyboard dismissal behavior.
319

320
```typescript { .api }
321
/**
322
 * Hook for keyboard dismissal management
323
 * @returns Keyboard dismissal utilities
324
 */
325
function useKeyboardDismissable(): KeyboardDismissReturn;
326

327
/**
328
 * Keyboard dismiss handler manager
329
 */
330
const keyboardDismissHandlerManager: {
331
  addHandler: (handler: () => void) => void;
332
  removeHandler: (handler: () => void) => void;
333
  dismissKeyboard: () => void;
334
};
335

336
interface KeyboardDismissReturn {
337
  dismiss: () => void;
338
  isKeyboardVisible: boolean;
339
}
340
```
341

342
### Utility Functions
343

344
#### DOM Utilities
345

346
```typescript { .api }
347
/**
348
 * Check if DOM is available (for web compatibility)
349
 * @returns Boolean indicating DOM availability
350
 */
351
function canUseDom(): boolean;
352
```
353

354
#### React Utilities
355

356
```typescript { .api }
357
/**
358
 * Merge multiple React refs into a single ref callback
359
 * @param refs - Array of refs to merge
360
 * @returns Merged ref callback function
361
 */
362
function mergeRefs<T>(...refs: React.Ref<T>[]): React.RefCallback<T>;
363

364
/**
365
 * Compose multiple event handlers into a single handler
366
 * @param handlers - Array of event handler functions
367
 * @returns Composed event handler
368
 */
369
function composeEventHandlers<T>(...handlers: Array<(event: T) => void>): (event: T) => void;
370

371
/**
372
 * Create a context with proper error handling
373
 * @param name - Context name for error messages
374
 * @param strict - Whether to throw error when context is undefined
375
 * @returns Context and useContext hook
376
 */
377
function createContext<T>(name: string, strict?: boolean): [React.Context<T>, () => T];
378
```
379

380
#### Children Utilities
381

382
```typescript { .api }
383
/**
384
 * Add spacing between child components
385
 * @param children - React children to space
386
 * @param space - Space value between children
387
 * @returns Children with spacing elements inserted
388
 */
389
function getSpacedChildren(children: React.ReactNode, space: any): React.ReactNode[];
390

391
/**
392
 * Get absolutely positioned children
393
 * @param children - React children to process
394
 * @returns Filtered absolutely positioned children
395
 */
396
function getAbsoluteChildren(children: React.ReactNode): React.ReactNode[];
397

398
/**
399
 * Get attached children for component composition
400
 * @param children - React children to process
401
 * @returns Processed attached children
402
 */
403
function getAttachedChildren(children: React.ReactNode): React.ReactNode[];
404

405
/**
406
 * Wrap string children with text components
407
 * @param child - Child element to process
408
 * @returns Wrapped child element
409
 */
410
function wrapStringChild(child: React.ReactNode): React.ReactNode;
411

412
/**
413
 * Add text properties to string children
414
 * @param children - Children to process
415
 * @param props - Props to add to text elements
416
 * @returns Enhanced children with text props
417
 */
418
function addTextAndPropsToStrings(children: React.ReactNode, props: any): React.ReactNode;
419
```
420

421
#### Object Utilities
422

423
```typescript { .api }
424
/**
425
 * Check if object is empty
426
 * @param obj - Object to check
427
 * @returns Boolean indicating if object is empty
428
 */
429
function isEmptyObj(obj: any): boolean;
430

431
/**
432
 * Combine context values with component props
433
 * @param context - Context values
434
 * @param props - Component props
435
 * @returns Combined props object
436
 */
437
function combineContextAndProps(context: any, props: any): any;
438
```
439

440
#### Accessibility Utilities
441

442
```typescript { .api }
443
/**
444
 * Generate appropriate ARIA attribute value
445
 * @param condition - Boolean condition for attribute
446
 * @returns Appropriate ARIA attribute value
447
 */
448
function ariaAttr(condition: boolean): boolean | undefined;
449
```
450

451
#### Style Utilities
452

453
```typescript { .api }
454
/**
455
 * Resolve stack style input for spacing and layout
456
 * @param input - Style input to resolve
457
 * @returns Resolved style properties
458
 */
459
function resolveStackStyleInput(input: any): any;
460

461
/**
462
 * Get style element for web styling
463
 * @returns Style element or null
464
 */
465
function getStyleElement(): HTMLStyleElement | null;
466
```
467

468
### Prop Resolution Utilities
469

470
```typescript { .api }
471
/**
472
 * Hook for comprehensive props resolution with theme integration
473
 * @param props - Props to resolve
474
 * @returns Resolved props with theme values
475
 */
476
function usePropsResolution(props: any): any;
477

478
/**
479
 * Hook for props resolution testing and debugging
480
 * @param props - Props to test resolution for
481
 * @returns Resolution test results
482
 */
483
function usePropsResolutionTest(props: any): any;
484
```