0
# Utilities and Contexts
1

2
Utility functions, constants, React contexts, and helper components that support the Reactstrap component ecosystem.
3

4
## Capabilities
5

6
### Util Namespace
7

8
Collection of utility functions for common operations and CSS module integration.
9

10
```javascript { .api }
11
/**
12
 * Utility functions namespace
13
 */
14
namespace Util {
15
  /**
16
   * Map CSS class names to CSS Modules
17
   * @param className - Space-separated class names
18
   * @param cssModule - CSS Module mapping object
19
   * @returns Mapped class names string
20
   */
21
  function mapToCssModules(className?: string, cssModule?: object): string;
22

23
  /**
24
   * Remove specified keys from an object
25
   * @param obj - Source object
26
   * @param omitKeys - Array of keys to remove
27
   * @returns New object without omitted keys
28
   */
29
  function omit(obj: object, omitKeys: string[]): object;
30

31
  /**
32
   * Select only specified keys from an object
33
   * @param obj - Source object  
34
   * @param keys - Array of keys to select
35
   * @returns New object with only selected keys
36
   */
37
  function pick(obj: object, keys: string[]): object;
38

39
  /**
40
   * Set global CSS Module for all components
41
   * @param cssModule - Global CSS Module mapping
42
   */
43
  function setGlobalCssModule(cssModule: object): void;
44

45
  /**
46
   * Get browser scrollbar width
47
   * @returns Scrollbar width in pixels
48
   */
49
  function getScrollbarWidth(): number;
50

51
  /**
52
   * Set body padding to account for scrollbar
53
   * @param padding - Padding value in pixels
54
   */
55
  function setScrollbarWidth(padding: number): void;
56

57
  /**
58
   * Check if document body overflows viewport
59
   * @returns True if body overflows
60
   */
61
  function isBodyOverflowing(): boolean;
62

63
  /**
64
   * Get original body padding-right value
65
   * @returns Original padding in pixels
66
   */
67
  function getOriginalBodyPadding(): number;
68

69
  /**
70
   * Conditionally update scrollbar based on overflow
71
   */
72
  function conditionallyUpdateScrollbar(): void;
73

74
  /**
75
   * Display deprecation warning once per message
76
   * @param message - Warning message to display
77
   */
78
  function warnOnce(message: string): void;
79

80
  /**
81
   * Create deprecated prop type validator
82
   * @param propType - Original prop type validator
83
   * @param explanation - Deprecation explanation
84
   * @returns Deprecated prop type validator
85
   */
86
  function deprecated(propType: Function, explanation: string): Function;
87

88
  /**
89
   * Find DOM elements from various target types
90
   * @param target - Target selector, element, or function
91
   * @returns DOM element or NodeList
92
   */
93
  function findDOMElements(target: string | Element | Function): Element | NodeList;
94

95
  /**
96
   * Get target element(s) with optional multiple selection
97
   * @param target - Target selector, element, or function
98
   * @param allElements - Return all matching elements
99
   * @returns Single element or array of elements
100
   */
101
  function getTarget(target: any, allElements?: boolean): Element | Element[];
102

103
  /**
104
   * Add event listeners to multiple elements
105
   * @param els - Elements or element array
106
   * @param handler - Event handler function
107
   * @param events - Event types to listen for
108
   * @param useCapture - Use capture phase
109
   * @returns Function to remove all listeners
110
   */
111
  function addMultipleEventListeners(
112
    els: Element | Element[],
113
    handler: Function,
114
    events: string | string[],
115
    useCapture?: boolean
116
  ): () => void;
117

118
  /**
119
   * Check if value is React ref object
120
   * @param target - Value to check
121
   * @returns True if React ref object
122
   */
123
  function isReactRefObj(target: any): boolean;
124

125
  /**
126
   * Check if value is object type
127
   * @param value - Value to check
128
   * @returns True if object
129
   */
130
  function isObject(value: any): boolean;
131

132
  /**
133
   * Convert value to number
134
   * @param value - Value to convert
135
   * @returns Numeric value or NaN
136
   */
137
  function toNumber(value: any): number;
138

139
  /**
140
   * Check if value is function
141
   * @param value - Value to check
142
   * @returns True if function
143
   */
144
  function isFunction(value: any): boolean;
145

146
  /**
147
   * Check if value is array or NodeList
148
   * @param els - Value to check
149
   * @returns True if array or NodeList
150
   */
151
  function isArrayOrNodeList(els: any): boolean;
152

153
  /**
154
   * Merge default props with component props
155
   * @param defaultProps - Default prop values
156
   * @param props - Component props
157
   * @returns Merged props object
158
   */
159
  function addDefaultProps(defaultProps: object, props: object): object;
160
}
161
```
162

163
### Constants
164

165
Predefined constants used throughout the Reactstrap ecosystem.
166

167
```javascript { .api }
168
/**
169
 * Animation timeouts matching Bootstrap CSS variables
170
 */
171
const TransitionTimeouts: {
172
  Fade: 150;
173
  Collapse: 350;
174
  Modal: 300;
175
  Carousel: 600;
176
  Offcanvas: 300;
177
};
178

179
/**
180
 * Keyboard key codes for interaction handling
181
 */
182
const keyCodes: {
183
  esc: 27;
184
  space: 32;
185
  enter: 13;
186
  tab: 9;
187
  up: 38;
188
  down: 40;
189
  home: 36;
190
  end: 35;
191
  n: 78;
192
  p: 80;
193
};
194

195
/**
196
 * Valid Popper.js placement options
197
 */
198
const PopperPlacements: string[];
199

200
/**
201
 * Default toggle events for interactive components
202
 */
203
const defaultToggleEvents: string[];
204

205
/**
206
 * CSS selector for focusable elements
207
 */
208
const focusableElements: string[];
209

210
/**
211
 * Transition status constants
212
 */
213
const TransitionStatuses: {
214
  ENTERING: 'entering';
215
  ENTERED: 'entered';
216
  EXITING: 'exiting';
217
  EXITED: 'exited';
218
};
219

220
/**
221
 * Transition prop type keys
222
 */
223
const TransitionPropTypeKeys: string[];
224

225
/**
226
 * Boolean indicating DOM availability
227
 */
228
const canUseDOM: boolean;
229
```
230

231
### PropTypes
232

233
Custom PropType validators for component props.
234

235
```javascript { .api }
236
/**
237
 * PropType for DOM element references
238
 */
239
const DOMElement: PropTypes.Validator;
240

241
/**
242
 * PropType for component target elements
243
 */
244
const targetPropType: PropTypes.Validator;
245

246
/**
247
 * PropType for HTML tag or React component
248
 */
249
const tagPropType: PropTypes.Validator;
250
```
251

252
### React Contexts
253

254
React Context objects for component state sharing.
255

256
```javascript { .api }
257
/**
258
 * Context for dropdown component state
259
 */
260
const DropdownContext: React.Context<{
261
  toggle: () => void;
262
  isOpen: boolean;
263
  direction: string;
264
  inNavbar: boolean;
265
  disabled: boolean;
266
}>;
267

268
/**
269
 * Context for accordion component state
270
 */
271
const AccordionContext: React.Context<{
272
  open: string | string[];
273
  toggle: (id: string) => void;
274
  stayOpen: boolean;
275
}>;
276
```
277

278
### Helper Components
279

280
Utility components for advanced functionality.
281

282
```javascript { .api }
283
/**
284
 * Fade transition component
285
 * @param props.baseClass - Base CSS class for transition
286
 * @param props.baseClassActive - Active state CSS class
287
 * @param props.tag - HTML element to render as (default: 'div')
288
 * @param props.className - Additional CSS classes
289
 * @param props.cssModule - CSS Module mapping object
290
 * @param props.children - Content to animate
291
 * @param props.in - Control transition state
292
 * @param props.appear - Run transition on initial mount
293
 * @param props.enter - Enable enter transitions
294
 * @param props.exit - Enable exit transitions
295
 * @param props.timeout - Transition duration
296
 * @param props.onEnter - Callback when entering
297
 * @param props.onEntering - Callback while entering
298
 * @param props.onEntered - Callback when entered
299
 * @param props.onExit - Callback when exiting
300
 * @param props.onExiting - Callback while exiting
301
 * @param props.onExited - Callback when exited
302
 */
303
function Fade(props: {
304
  baseClass?: string;
305
  baseClassActive?: string;
306
  tag?: React.ElementType;
307
  className?: string;
308
  cssModule?: object;
309
  children?: React.ReactNode;
310
  in?: boolean;
311
  appear?: boolean;
312
  enter?: boolean;
313
  exit?: boolean;
314
  timeout?: number;
315
  onEnter?: () => void;
316
  onEntering?: () => void;
317
  onEntered?: () => void;
318
  onExit?: () => void;
319
  onExiting?: () => void;
320
  onExited?: () => void;
321
}): JSX.Element;
322

323
/**
324
 * Popper.js content wrapper for positioning
325
 */
326
function PopperContent(props: {
327
  placement?: string;
328
  isOpen?: boolean;
329
  target: any;
330
  container?: any;
331
  modifiers?: object[];
332
  strategy?: string;
333
  offset?: [number, number];
334
  flip?: boolean;
335
  shift?: boolean;
336
  preventOverflow?: boolean;
337
  arrow?: boolean;
338
  transform?: boolean;
339
  children?: React.ReactNode;
340
}): JSX.Element;
341

342
/**
343
 * Helper for Popper.js target elements
344
 */
345
function PopperTargetHelper(props: {
346
  placement?: string;
347
  isOpen?: boolean;
348
  target: any;
349
  container?: any;
350
  children?: React.ReactNode;
351
}): JSX.Element;
352
```
353

354
### Polyfill Namespace
355

356
Browser compatibility polyfills for older environments.
357

358
```javascript { .api }
359
/**
360
 * Browser polyfills namespace
361
 */
362
namespace Polyfill {
363
  /**
364
   * CustomEvent polyfill for IE
365
   */
366
  function CustomEvent(event: string, params?: object): Event;
367

368
  /**
369
   * Object.values polyfill for older browsers
370
   */
371
  function values(obj: object): any[];
372
}
373
```
374

375
## Usage Examples
376

377
### CSS Modules Integration
378

379
```jsx
380
import { Button } from 'reactstrap';
381
import { setGlobalCssModule } from 'reactstrap/lib/utils';
382
import styles from './styles.module.css';
383

384
// Set global CSS module
385
setGlobalCssModule(styles);
386

387
function StyledButton() {
388
  return (
389
    <Button 
390
      color="primary"
391
      className="custom-button"
392
      cssModule={styles}
393
    >
394
      Styled Button
395
    </Button>
396
  );
397
}
398
```
399

400
### Utility Functions
401

402
```jsx
403
import { omit, pick, mapToCssModules } from 'reactstrap/lib/utils';
404

405
function UtilityExample() {
406
  const props = {
407
    color: 'primary',
408
    size: 'lg',
409
    onClick: () => {},
410
    'data-test': 'button'
411
  };
412

413
  // Remove internal props
414
  const htmlProps = omit(props, ['color', 'size']);
415
  
416
  // Select only specific props
417
  const buttonProps = pick(props, ['color', 'size']);
418
  
419
  // Map CSS classes
420
  const classes = mapToCssModules('btn btn-primary', cssModule);
421

422
  return <button className={classes} {...htmlProps} />;
423
}
424
```
425

426
### Using Contexts
427

428
```jsx
429
import { useContext } from 'react';
430
import { DropdownContext } from 'reactstrap';
431

432
function CustomDropdownItem() {
433
  const { toggle, isOpen } = useContext(DropdownContext);
434

435
  return (
436
    <button onClick={toggle}>
437
      Custom Item (Dropdown is {isOpen ? 'open' : 'closed'})
438
    </button>
439
  );
440
}
441
```
442

443
### Fade Transition
444

445
```jsx
446
import { Fade, Button } from 'reactstrap';
447

448
function FadeExample() {
449
  const [fadeIn, setFadeIn] = useState(true);
450

451
  return (
452
    <div>
453
      <Button color="primary" onClick={() => setFadeIn(!fadeIn)}>
454
        Toggle Fade
455
      </Button>
456
      <Fade in={fadeIn}>
457
        <div className="mt-3">
458
          This content will fade in and out!
459
        </div>
460
      </Fade>
461
    </div>
462
  );
463
}
464
```
465

466
### Constants Usage
467

468
```jsx
469
import { TransitionTimeouts, keyCodes } from 'reactstrap/lib/utils';
470

471
function CustomComponent() {
472
  const handleKeyDown = (event) => {
473
    if (event.keyCode === keyCodes.esc) {
474
      // Handle escape key
475
    }
476
  };
477

478
  return (
479
    <div 
480
      onKeyDown={handleKeyDown}
481
      style={{ 
482
        transition: `opacity ${TransitionTimeouts.Fade}ms ease-in-out` 
483
      }}
484
    >
485
      Custom component with Reactstrap timing
486
    </div>
487
  );
488
}
489
```
490

491
## Polyfill Namespace
492

493
Browser polyfills for older environments. Automatically patches missing APIs when imported.
494

495
```javascript { .api }
496
/**
497
 * Polyfill namespace providing browser compatibility patches
498
 * Includes polyfills for:
499
 * - CustomEvent constructor for legacy IE support
500
 * - Object.values for older JavaScript environments
501
 * 
502
 * Import to automatically patch the global environment:
503
 * import 'reactstrap/lib/polyfill';
504
 * 
505
 * Or access via namespace:
506
 * import { Polyfill } from 'reactstrap';
507
 */
508
namespace Polyfill {
509
  // Polyfills are automatically applied when imported
510
  // No direct API - patches global objects
511
}
512
```