0
# Utilities & Services
1
2
Core utilities, services, and helper components that provide foundational functionality across the library.
3
4
## Capabilities
5
6
### Global API Configuration
7
8
Central configuration system for PrimeReact library settings and behavior.
9
10
```typescript { .api }
11
/**
12
* Get or set global locale configuration
13
* @param locale - Locale identifier (e.g., 'en', 'es', 'fr')
14
*/
15
function locale(locale?: string): string | void;
16
17
/**
18
* Add custom locale configuration
19
* @param locale - Locale identifier
20
* @param options - Locale configuration object
21
*/
22
function addLocale(locale: string, options: LocaleOptions): void;
23
24
/**
25
* Global PrimeReact API configuration object
26
*/
27
interface PrimeReactAPI {
28
/** Global ripple effect toggle */
29
ripple: boolean;
30
/** Global input styling mode */
31
inputStyle: 'outlined' | 'filled';
32
/** Global locale setting */
33
locale: string;
34
/** Global append target for overlays */
35
appendTo: HTMLElement | string | null;
36
/** Automatic z-index management */
37
autoZIndex: boolean;
38
/** Base z-index value */
39
zIndex: {
40
modal: number;
41
overlay: number;
42
menu: number;
43
tooltip: number;
44
};
45
/** Hide overlays on document scrolling */
46
hideOverlaysOnDocumentScrolling: boolean;
47
/** CSP nonce for inline styles */
48
nonce: string | undefined;
49
/** Null sort order for DataTable */
50
nullSortOrder: 1 | -1;
51
/** Global filter match mode options */
52
filterMatchModeOptions: {
53
text: FilterMatchModeOption[];
54
numeric: FilterMatchModeOption[];
55
date: FilterMatchModeOption[];
56
};
57
}
58
59
interface LocaleOptions {
60
firstDayOfWeek?: number;
61
dayNames?: string[];
62
dayNamesShort?: string[];
63
dayNamesMin?: string[];
64
monthNames?: string[];
65
monthNamesShort?: string[];
66
today?: string;
67
clear?: string;
68
dateFormat?: string;
69
weekHeader?: string;
70
[key: string]: any;
71
}
72
73
interface FilterMatchModeOption {
74
label: string;
75
value: string;
76
}
77
```
78
79
**Usage Examples:**
80
81
```typescript
82
import { locale, addLocale, PrimeReactAPI } from "primereact/api";
83
84
// Set global locale
85
locale('en');
86
87
// Add custom locale
88
addLocale('custom', {
89
firstDayOfWeek: 1,
90
dayNames: ['Sunday', 'Monday', 'Tuesday', 'Wednesday', 'Thursday', 'Friday', 'Saturday'],
91
monthNames: ['January', 'February', 'March', 'April', 'May', 'June', 'July', 'August', 'September', 'October', 'November', 'December'],
92
today: 'Today',
93
clear: 'Clear'
94
});
95
96
// Configure global settings
97
PrimeReactAPI.ripple = true;
98
PrimeReactAPI.inputStyle = 'outlined';
99
PrimeReactAPI.autoZIndex = true;
100
```
101
102
### React Hooks
103
104
Custom React hooks for common functionality and lifecycle management.
105
106
```typescript { .api }
107
/**
108
* Hook for managing event listeners with cleanup
109
* @param options - Event listener configuration
110
*/
111
function useEventListener(options: EventListenerOptions): void;
112
113
interface EventListenerOptions {
114
type: string;
115
listener: EventListener;
116
target?: EventTarget | null;
117
options?: boolean | AddEventListenerOptions;
118
}
119
120
/**
121
* Hook that runs effect only on updates, not on mount
122
* @param fn - Effect function
123
* @param deps - Dependency array
124
*/
125
function useUpdateEffect(fn: () => void | (() => void), deps: React.DependencyList): void;
126
127
/**
128
* Hook that returns the previous value of a variable
129
* @param value - Current value
130
* @returns Previous value
131
*/
132
function usePrevious<T>(value: T): T | undefined;
133
134
/**
135
* Hook for detecting clicks outside a component
136
* @param ref - Reference to the component element
137
* @param callback - Function to call when outside click occurs
138
*/
139
function useClickOutside<T extends HTMLElement>(
140
ref: React.RefObject<T>,
141
callback: () => void
142
): void;
143
144
/**
145
* Hook for managing resize event listeners
146
* @param listener - Resize event handler
147
* @param target - Target element (defaults to window)
148
*/
149
function useResizeListener(listener: () => void, target?: EventTarget): void;
150
151
/**
152
* Hook for handling overlay scroll events
153
* @param options - Scroll handling configuration
154
*/
155
function useOverlayScrollListener(options: OverlayScrollListenerOptions): void;
156
157
interface OverlayScrollListenerOptions {
158
target: React.RefObject<HTMLElement>;
159
overlay: React.RefObject<HTMLElement>;
160
listener: () => void;
161
when?: boolean;
162
}
163
164
/**
165
* Hook for managing display order of overlays
166
* @param overlayRef - Reference to overlay element
167
* @param visible - Visibility state
168
*/
169
function useDisplayOrder(overlayRef: React.RefObject<HTMLElement>, visible: boolean): void;
170
171
/**
172
* Effect hook that only runs on component unmount
173
* @param fn - Cleanup function
174
*/
175
function useUnmountEffect(fn: () => void): void;
176
```
177
178
### Utility Classes
179
180
Core utility classes for DOM manipulation, object operations, and component helpers.
181
182
```typescript { .api }
183
/**
184
* Object manipulation utilities
185
*/
186
class ObjectUtils {
187
/** Check if value is empty (null, undefined, empty string/array/object) */
188
static isEmpty(value: any): boolean;
189
190
/** Check if value is not empty */
191
static isNotEmpty(value: any): boolean;
192
193
/** Deep merge objects */
194
static merge(target: object, ...sources: object[]): object;
195
196
/** Get nested property value by path */
197
static resolveFieldData(data: any, field: string): any;
198
199
/** Check if objects are equal */
200
static equals(obj1: any, obj2: any, field?: string): boolean;
201
202
/** Deep clone object */
203
static deepEquals(a: any, b: any): boolean;
204
205
/** Remove accents from string */
206
static removeAccents(str: string): string;
207
208
/** Check if value is array */
209
static isArray(value: any): boolean;
210
211
/** Check if value is date */
212
static isDate(value: any): boolean;
213
214
/** Check if value is function */
215
static isFunction(value: any): boolean;
216
217
/** Check if value is object */
218
static isObject(value: any): boolean;
219
}
220
221
/**
222
* DOM manipulation utilities
223
*/
224
class DomHandler {
225
/** Add CSS class to element */
226
static addClass(element: Element, className: string): void;
227
228
/** Remove CSS class from element */
229
static removeClass(element: Element, className: string): void;
230
231
/** Check if element has CSS class */
232
static hasClass(element: Element, className: string): boolean;
233
234
/** Find single element by selector */
235
static find(element: Element, selector: string): Element;
236
237
/** Find multiple elements by selector */
238
static findSingle(element: Element, selector: string): Element;
239
240
/** Get element index within parent */
241
static index(element: Element): number;
242
243
/** Get element offset position */
244
static getOffset(element: Element): { top: number; left: number };
245
246
/** Get element width */
247
static getWidth(element: Element): number;
248
249
/** Get element height */
250
static getHeight(element: Element): number;
251
252
/** Get scrollbar width */
253
static calculateScrollbarWidth(): number;
254
255
/** Invoke function on next animation frame */
256
static invokeElementMethod(element: Element, methodName: string, args?: any[]): any;
257
258
/** Check if element is visible */
259
static isVisible(element: Element): boolean;
260
261
/** Get viewport */
262
static getViewport(): { width: number; height: number };
263
264
/** Get element outline width */
265
static getOuterWidth(element: Element, margin?: boolean): number;
266
267
/** Get element outline height */
268
static getOuterHeight(element: Element, margin?: boolean): number;
269
270
/** Fade in element */
271
static fadeIn(element: Element, duration: number): void;
272
273
/** Fade out element */
274
static fadeOut(element: Element, duration: number): void;
275
276
/** Get user agent */
277
static getUserAgent(): string;
278
279
/** Check if browser */
280
static isIOS(): boolean;
281
static isAndroid(): boolean;
282
static isTouchDevice(): boolean;
283
}
284
285
/**
286
* Z-index management utilities
287
*/
288
class ZIndexUtils {
289
/** Get current z-index */
290
static getCurrent(): number;
291
292
/** Get new z-index */
293
static getNext(): number;
294
295
/** Set z-index for element */
296
static set(key: string, element: HTMLElement, baseZIndex?: number): void;
297
298
/** Clear z-index for element */
299
static clear(element: HTMLElement): void;
300
}
301
302
/**
303
* Generate unique component ID
304
* @param prefix - Optional prefix for the ID
305
* @returns Unique identifier string
306
*/
307
function UniqueComponentId(prefix?: string): string;
308
```
309
310
### Event Bus
311
312
Global event communication system for component interaction.
313
314
```typescript { .api }
315
/**
316
* Global event bus for component communication
317
*/
318
class EventBus {
319
/** Subscribe to event */
320
static on(event: string, callback: Function): void;
321
322
/** Unsubscribe from event */
323
static off(event: string, callback: Function): void;
324
325
/** Emit event */
326
static emit(event: string, ...args: any[]): void;
327
}
328
```
329
330
### Portal
331
332
React portal component for rendering content outside the component tree.
333
334
```typescript { .api }
335
/**
336
* React portal component for rendering outside component tree
337
* @param props - Portal configuration options
338
* @returns JSX element
339
*/
340
function Portal(props: PortalProps): JSX.Element;
341
342
interface PortalProps {
343
/** Content to portal */
344
children?: React.ReactNode;
345
/** Target element or selector */
346
element?: HTMLElement | string;
347
/** Append to document body */
348
appendTo?: HTMLElement | string;
349
/** Visible state */
350
visible?: boolean;
351
/** Show event handler */
352
onMounted?: (el: HTMLElement) => void;
353
/** Hide event handler */
354
onUnmounted?: (el: HTMLElement) => void;
355
}
356
```
357
358
### CSS Transition
359
360
CSS transition wrapper component for smooth animations.
361
362
```typescript { .api }
363
/**
364
* CSS transition wrapper component
365
* @param props - CSSTransition configuration options
366
* @returns JSX element
367
*/
368
function CSSTransition(props: CSSTransitionProps): JSX.Element;
369
370
interface CSSTransitionProps {
371
/** Child element to animate */
372
children?: React.ReactNode;
373
/** Transition enabled */
374
in?: boolean;
375
/** CSS class prefix for transition states */
376
classNames?: string;
377
/** Transition timeout */
378
timeout?: number;
379
/** Unmount on exit */
380
unmountOnExit?: boolean;
381
/** Enter transition handler */
382
onEnter?: (node: HTMLElement) => void;
383
/** Enter transition complete handler */
384
onEntered?: (node: HTMLElement) => void;
385
/** Exit transition handler */
386
onExit?: (node: HTMLElement) => void;
387
/** Exit transition complete handler */
388
onExited?: (node: HTMLElement) => void;
389
}
390
```
391
392
### Ripple Effect
393
394
Material design ripple effect component for interactive feedback.
395
396
```typescript { .api }
397
/**
398
* Material design ripple effect component
399
* @param props - Ripple configuration options
400
* @returns JSX element
401
*/
402
function Ripple(props: RippleProps): JSX.Element;
403
404
interface RippleProps {
405
/** CSS class name */
406
className?: string;
407
/** Passthrough options */
408
pt?: PassThroughOptions;
409
}
410
```
411
412
### Tooltip
413
414
Tooltip component for providing contextual information on hover or focus.
415
416
```typescript { .api }
417
/**
418
* Tooltip component for contextual information
419
* @param props - Tooltip configuration options
420
* @returns JSX element
421
*/
422
function Tooltip(props: TooltipProps): JSX.Element;
423
424
interface TooltipProps {
425
/** Target element selector or reference */
426
target?: string | React.RefObject<HTMLElement>;
427
/** Tooltip content */
428
content?: string;
429
/** Position relative to target */
430
position?: 'right' | 'left' | 'top' | 'bottom';
431
/** Event that triggers tooltip */
432
event?: 'hover' | 'focus';
433
/** Hide event */
434
hideEvent?: 'hover' | 'blur';
435
/** Show delay in milliseconds */
436
showDelay?: number;
437
/** Hide delay in milliseconds */
438
hideDelay?: number;
439
/** Auto hide enabled */
440
autoHide?: boolean;
441
/** Show on disabled elements */
442
showOnDisabled?: boolean;
443
/** CSS class name */
444
className?: string;
445
/** Passthrough options */
446
pt?: PassThroughOptions;
447
}
448
449
/**
450
* Global tooltip options interface
451
*/
452
interface TooltipOptions {
453
tooltip?: string;
454
tooltipOptions?: {
455
className?: string;
456
position?: 'right' | 'left' | 'top' | 'bottom';
457
event?: 'hover' | 'focus';
458
showDelay?: number;
459
hideDelay?: number;
460
};
461
}
462
```
463
464
### Overlay Services
465
466
Services for managing overlay components like dialogs, popups, and tooltips.
467
468
```typescript { .api }
469
/**
470
* Overlay management service
471
*/
472
class OverlayService {
473
/** Show overlay */
474
static show(overlay: HTMLElement, target: HTMLElement, options?: OverlayOptions): void;
475
476
/** Hide overlay */
477
static hide(overlay: HTMLElement): void;
478
479
/** Check if overlay is visible */
480
static isVisible(overlay: HTMLElement): boolean;
481
}
482
483
interface OverlayOptions {
484
position?: 'center' | 'top' | 'bottom' | 'left' | 'right';
485
modal?: boolean;
486
dismissable?: boolean;
487
showTransition?: string;
488
hideTransition?: string;
489
}
490
491
/**
492
* Terminal service for Terminal component
493
*/
494
class TerminalService {
495
/** Send command to terminal */
496
static sendCommand(command: string): void;
497
498
/** Subscribe to command events */
499
static on(event: 'command' | 'response', callback: Function): void;
500
501
/** Unsubscribe from events */
502
static off(event: 'command' | 'response', callback: Function): void;
503
}
504
```