0
# Utilities
1

2
jQuery UI provides core utilities and helper functions that support the widget system and can be used independently for common UI tasks.
3

4
## Capabilities
5

6
### Position Utility
7

8
Advanced element positioning system with collision detection and flexible alignment options.
9

10
```javascript { .api }
11
/**
12
 * Positions element relative to another element with collision detection
13
 * @param {PositionOptions} options - Position configuration
14
 * @returns {jQuery} Positioned element for chaining
15
 */
16
$(element).position(options);
17

18
/**
19
 * Gets browser scrollbar width
20
 * @returns {number} Scrollbar width in pixels
21
 */
22
$.position.scrollbarWidth();
23

24
interface PositionOptions {
25
  my?: string;                       // Position of element to align (default: "center")
26
  at?: string;                       // Position of target to align to (default: "center")
27
  of?: string | Element | Event;     // Target element or position
28
  collision?: string;                // Collision handling: "flip", "fit", "flipfit", "none"
29
  using?: (position: {top: number, left: number}, feedback: object) => void; // Custom positioning function
30
  within?: string | Element;         // Constraining element (default: window)
31
}
32
```
33

34
**Position Values:**
35
- Horizontal: `"left"`, `"center"`, `"right"`, or offset like `"left+10"`
36
- Vertical: `"top"`, `"center"`, `"bottom"`, or offset like `"top-5"`
37
- Combined: `"left top"`, `"center center"`, `"right bottom"`, etc.
38

39
**Collision Detection:**
40
```javascript { .api }
41
// Collision handlers available
42
$.ui.position.fit.left;              // Fit collision handler for left edge
43
$.ui.position.fit.right;             // Fit collision handler for right edge  
44
$.ui.position.fit.top;               // Fit collision handler for top edge
45
$.ui.position.fit.bottom;            // Fit collision handler for bottom edge
46

47
$.ui.position.flip.left;             // Flip collision handler for left edge
48
$.ui.position.flip.right;            // Flip collision handler for right edge
49
$.ui.position.flip.top;              // Flip collision handler for top edge
50
$.ui.position.flip.bottom;           // Flip collision handler for bottom edge
51
```
52

53
**Usage Examples:**
54
```javascript
55
// Center dialog in window
56
$('#dialog').position({
57
  my: "center",
58
  at: "center",
59
  of: window
60
});
61

62
// Position tooltip above element
63
$('#tooltip').position({
64
  my: "center bottom",
65
  at: "center top",
66
  of: "#trigger",
67
  collision: "flip"
68
});
69

70
// Position with custom logic
71
$('#menu').position({
72
  my: "left top",
73
  at: "left bottom",
74
  of: "#button",
75
  using: function(position, feedback) {
76
    $(this).css(position);
77
    $(this).addClass(feedback.horizontal + " " + feedback.vertical);
78
  }
79
});
80
```
81

82
### Keyboard Constants
83

84
Standardized key code constants for keyboard event handling.
85

86
```javascript { .api }
87
// Key code constants
88
$.ui.keyCode.BACKSPACE;              // 8
89
$.ui.keyCode.COMMA;                  // 188
90
$.ui.keyCode.DELETE;                 // 46
91
$.ui.keyCode.DOWN;                   // 40
92
$.ui.keyCode.END;                    // 35
93
$.ui.keyCode.ENTER;                  // 13
94
$.ui.keyCode.ESCAPE;                 // 27
95
$.ui.keyCode.HOME;                   // 36
96
$.ui.keyCode.LEFT;                   // 37
97
$.ui.keyCode.PAGE_DOWN;              // 34
98
$.ui.keyCode.PAGE_UP;                // 33
99
$.ui.keyCode.PERIOD;                 // 190
100
$.ui.keyCode.RIGHT;                  // 39
101
$.ui.keyCode.SPACE;                  // 32
102
$.ui.keyCode.TAB;                    // 9
103
$.ui.keyCode.UP;                     // 38
104
```
105

106
**Usage Examples:**
107
```javascript
108
$(document).keydown(function(event) {
109
  switch(event.keyCode) {
110
    case $.ui.keyCode.ESCAPE:
111
      closeDialog();
112
      break;
113
    case $.ui.keyCode.ENTER:
114
      submitForm();
115
      break;
116
    case $.ui.keyCode.TAB:
117
      // Handle tab navigation
118
      break;
119
  }
120
});
121
```
122

123
### Focus Management
124

125
Utilities for managing focus and determining focusable elements.
126

127
```javascript { .api }
128
/**
129
 * Determines if element can receive focus
130
 * @param {Element} element - Element to test
131
 * @param {boolean} hasTabindex - Whether element has explicit tabindex
132
 * @returns {boolean} True if element is focusable
133
 */
134
$.ui.focusable(element, hasTabindex);
135

136
/**
137
 * Determines if element can be tabbed to
138
 * @param {Element} element - Element to test
139
 * @returns {boolean} True if element is tabbable
140
 */
141
$.ui.tabbable(element);
142

143
/**
144
 * Custom selectors for focusable elements
145
 */
146
$(':focusable');                     // Selects all focusable elements
147
$(':tabbable');                      // Selects all tabbable elements
148
```
149

150
**Usage Examples:**
151
```javascript
152
// Find all focusable elements in container
153
var focusableElements = $('#container').find(':focusable');
154

155
// Check if specific element can receive focus
156
if ($.ui.focusable($('#my-element')[0])) {
157
  $('#my-element').focus();
158
}
159

160
// Trap focus within dialog
161
$('#dialog').on('keydown', function(event) {
162
  if (event.keyCode === $.ui.keyCode.TAB) {
163
    var tabbableElements = $(this).find(':tabbable');
164
    // Handle tab navigation within dialog
165
  }
166
});
167
```
168

169
### Safe Element Access
170

171
Utilities for safely accessing DOM elements and their properties.
172

173
```javascript { .api }
174
/**
175
 * Safely gets document.activeElement avoiding IE errors
176
 * @param {Document} document - Document to check
177
 * @returns {Element} Active element or body if error
178
 */
179
$.ui.safeActiveElement(document);
180

181
/**
182
 * Safely blurs an element without errors
183
 * @param {Element} element - Element to blur
184
 */
185
$.ui.safeBlur(element);
186
```
187

188
**Usage Examples:**
189
```javascript
190
// Get currently focused element safely
191
var activeElement = $.ui.safeActiveElement(document);
192

193
// Safely blur element before focusing another
194
$.ui.safeBlur(currentElement);
195
newElement.focus();
196
```
197

198
### Scroll Parent Detection
199

200
Finds the nearest scrollable parent element for positioning calculations.
201

202
```javascript { .api }
203
/**
204
 * Finds the nearest scrollable parent element
205
 * @param {boolean} includeHidden - Include elements with hidden overflow
206
 * @returns {jQuery} Scrollable parent element
207
 */
208
$(element).scrollParent(includeHidden);
209
```
210

211
**Usage Examples:**
212
```javascript
213
// Find scrollable container for positioning
214
var scrollContainer = $('#element').scrollParent();
215

216
// Monitor scroll events on correct container
217
$('#element').scrollParent().on('scroll', function() {
218
  // Reposition element
219
});
220
```
221

222
### Unique ID Generation
223

224
Generates and manages unique IDs for elements that need them.
225

226
```javascript { .api }
227
/**
228
 * Generates unique ID for element if it doesn't have one
229
 * @returns {jQuery} Element for chaining
230
 */
231
$(element).uniqueId();
232

233
/**
234
 * Removes generated unique ID from element
235
 * @returns {jQuery} Element for chaining  
236
 */
237
$(element).removeUniqueId();
238
```
239

240
**Usage Examples:**
241
```javascript
242
// Ensure element has ID for ARIA references
243
$('#form-field').uniqueId();
244
var fieldId = $('#form-field').attr('id');
245
$('#field-label').attr('for', fieldId);
246

247
// Clean up generated IDs
248
$('#form-field').removeUniqueId();
249
```
250

251
### CSS Selector Escaping
252

253
Escapes special characters in CSS selectors for safe use.
254

255
```javascript { .api }
256
/**
257
 * Escapes CSS selector special characters
258
 * @param {string} selector - Selector string to escape
259
 * @returns {string} Escaped selector string
260
 */
261
$.ui.escapeSelector(selector);
262
```
263

264
**Usage Examples:**
265
```javascript
266
// Safely use dynamic IDs as selectors
267
var elementId = 'item:1.2';
268
var escapedId = $.ui.escapeSelector(elementId);
269
$('#' + escapedId).addClass('selected');
270

271
// Escape user input for selector use
272
var userInput = $('.special[chars]');
273
var safeSelector = $.ui.escapeSelector(userInput);
274
```
275

276
### Disable Selection
277

278
Prevents text selection on elements during interactions.
279

280
```javascript { .api }
281
/**
282
 * Disables text selection on element
283
 * @returns {jQuery} Element for chaining
284
 */
285
$(element).disableSelection();
286

287
/**
288
 * Enables text selection on element
289
 * @returns {jQuery} Element for chaining
290
 */
291
$(element).enableSelection();
292
```
293

294
**Usage Examples:**
295
```javascript
296
// Prevent text selection during drag operations
297
$('#draggable').draggable({
298
  start: function() {
299
    $(this).disableSelection();
300
  },
301
  stop: function() {
302
    $(this).enableSelection();
303
  }
304
});
305

306
// Disable selection on UI controls
307
$('.ui-button, .ui-slider').disableSelection();
308
```
309

310
### Version Information
311

312
Access to jQuery UI version information.
313

314
```javascript { .api }
315
/**
316
 * jQuery UI version string
317
 */
318
$.ui.version;                        // "1.13.3"
319
```
320

321
### Data Storage
322

323
Enhanced data storage utilities used by widgets.
324

325
```javascript { .api }
326
/**
327
 * Widget-safe data storage (avoids conflicts)
328
 * @param {string} key - Data key
329
 * @param {any} value - Data value
330
 * @returns {any} Stored value when getting
331
 */
332
$(element).data(key, value);
333
```
334

335
**Usage Examples:**
336
```javascript
337
// Store widget instance data
338
$('#element').data('ui-widget', widgetInstance);
339

340
// Check for existing widget instance
341
if ($('#element').data('ui-dialog')) {
342
  $('#element').dialog('open');
343
}
344
```
345

346
## Form Utilities
347

348
Special utilities for form element handling and reset detection.
349

350
```javascript { .api }
351
/**
352
 * Form reset mixin for widgets that need to respond to form resets
353
 */
354
$.ui.formResetMixin;
355

356
/**
357
 * Gets form element for input
358
 * @returns {jQuery} Form element or empty jQuery object
359
 */
360
$(input).form();
361

362
/**
363
 * Gets all labels associated with form element
364
 * @returns {jQuery} Associated label elements
365
 */
366
$(input).labels();
367
```
368

369
**Usage Examples:**
370
```javascript
371
// Handle form reset in custom widget
372
$.widget('ui.customWidget', {
373
  _create: function() {
374
    this._on(this.element.form(), {
375
      reset: this.refresh
376
    });
377
  }
378
});
379

380
// Update labels when widget changes
381
var labels = $('#input').labels();
382
labels.addClass('widget-active');
383
```
384

385
## Types
386

387
```javascript { .api }
388
// Position utility types
389
interface PositionOptions {
390
  my?: string;
391
  at?: string;
392
  of?: string | Element | Event | { pageX: number, pageY: number };
393
  collision?: string;
394
  using?: (position: { top: number, left: number }, feedback: PositionFeedback) => void;
395
  within?: string | Element;
396
}
397

398
interface PositionFeedback {
399
  element: {
400
    element: jQuery;
401
    left: number;
402
    top: number;
403
    width: number;
404
    height: number;
405
  };
406
  target: {
407
    element: jQuery;
408
    left: number;
409
    top: number;
410
    width: number;
411
    height: number;
412
  };
413
  horizontal: 'left' | 'center' | 'right';
414
  vertical: 'top' | 'middle' | 'bottom';
415
  important: 'horizontal' | 'vertical';
416
}
417

418
// Key code enumeration
419
interface KeyCodes {
420
  BACKSPACE: 8;
421
  COMMA: 188;
422
  DELETE: 46;
423
  DOWN: 40;
424
  END: 35;
425
  ENTER: 13;
426
  ESCAPE: 27;
427
  HOME: 36;
428
  LEFT: 37;
429
  PAGE_DOWN: 34;
430
  PAGE_UP: 33;
431
  PERIOD: 190;
432
  RIGHT: 39;
433
  SPACE: 32;
434
  TAB: 9;
435
  UP: 38;
436
}
437

438
// Utility function signatures
439
type FocusableTest = (element: Element, hasTabindex?: boolean) => boolean;
440
type TabbableTest = (element: Element) => boolean;
441
type SafeActiveElement = (document: Document) => Element;
442
type SafeBlur = (element: Element) => void;
443
type EscapeSelector = (selector: string) => string;
444
```