0
# Widgets
1
2
jQuery UI widgets are interactive UI components that follow a consistent pattern. All widgets share common methods and options while providing specialized functionality.
3
4
## Capabilities
5
6
### Base Widget Methods
7
8
All widgets inherit these methods from the jQuery UI Widget Factory:
9
10
```javascript { .api }
11
/**
12
* Destroys the widget instance and removes all functionality
13
*/
14
$(...).widgetName('destroy');
15
16
/**
17
* Disables the widget, preventing user interaction
18
*/
19
$(...).widgetName('disable');
20
21
/**
22
* Enables the widget, allowing user interaction
23
*/
24
$(...).widgetName('enable');
25
26
/**
27
* Gets or sets widget options
28
* @param {string} key - Option name
29
* @param {any} value - Option value (omit to get)
30
* @returns {any} Option value when getting
31
*/
32
$(...).widgetName('option', key, value);
33
34
/**
35
* Refreshes the widget's visual state
36
*/
37
$(...).widgetName('refresh');
38
39
/**
40
* Returns the main widget element
41
* @returns {jQuery} Widget element
42
*/
43
$(...).widgetName('widget');
44
```
45
46
### Accordion
47
48
Collapsible content panels organized in sections.
49
50
```javascript { .api }
51
/**
52
* Creates an accordion widget
53
* @param {AccordionOptions} options - Configuration options
54
*/
55
$(...).accordion(options);
56
57
/**
58
* Refreshes the accordion heights and recalculates
59
*/
60
$(...).accordion('refresh');
61
62
interface AccordionOptions {
63
active?: number | boolean; // Initially active panel (0-based index or false for closed)
64
animate?: boolean | number | string | object; // Animation settings
65
classes?: { // CSS classes to apply
66
'ui-accordion'?: string;
67
'ui-accordion-header'?: string;
68
'ui-accordion-content'?: string;
69
};
70
collapsible?: boolean; // Allow all panels to be closed
71
event?: string; // Event that triggers panel opening
72
header?: string; // Selector for header elements
73
heightStyle?: 'auto' | 'fill' | 'content'; // How to calculate heights
74
icons?: { // Icons for headers
75
header?: string;
76
activeHeader?: string;
77
};
78
}
79
```
80
81
**Events:**
82
- `accordionactivate` - Triggered after a panel is activated
83
- `accordionbeforeactivate` - Triggered before a panel is activated
84
85
### Autocomplete
86
87
Input field with dropdown suggestions based on user input.
88
89
```javascript { .api }
90
/**
91
* Creates an autocomplete widget
92
* @param {AutocompleteOptions} options - Configuration options
93
*/
94
$(...).autocomplete(options);
95
96
/**
97
* Closes the autocomplete menu
98
*/
99
$(...).autocomplete('close');
100
101
/**
102
* Triggers a search programmatically
103
* @param {string} value - Value to search for
104
*/
105
$(...).autocomplete('search', value);
106
107
interface AutocompleteOptions {
108
appendTo?: string | Element; // Element to append menu to
109
autoFocus?: boolean; // Auto-focus first item
110
delay?: number; // Delay in milliseconds before triggering search
111
disabled?: boolean; // Disable the widget
112
minLength?: number; // Minimum characters before triggering search
113
position?: object; // Position options for menu
114
source: string | Array | Function; // Data source for suggestions
115
}
116
```
117
118
**Events:**
119
- `autocompletechange` - Triggered when field value changes
120
- `autocompleteclose` - Triggered when menu closes
121
- `autocompletefocus` - Triggered when menu item receives focus
122
- `autocompleteopen` - Triggered when menu opens
123
- `autocompleteresponse` - Triggered after search completes
124
- `autocompletesearch` - Triggered before search starts
125
- `autocompleteselect` - Triggered when menu item is selected
126
127
### Button
128
129
Enhanced button with theming and icon support.
130
131
```javascript { .api }
132
/**
133
* Creates a button widget
134
* @param {ButtonOptions} options - Configuration options
135
*/
136
$(...).button(options);
137
138
/**
139
* Refreshes the button's visual state
140
*/
141
$(...).button('refresh');
142
143
interface ButtonOptions {
144
classes?: object; // CSS classes to apply
145
disabled?: boolean; // Disable the button
146
icon?: string; // Icon class to display
147
iconPosition?: 'beginning' | 'end'; // Icon position relative to text
148
label?: string; // Button text
149
showLabel?: boolean; // Whether to show text with icon
150
}
151
```
152
153
### Checkboxradio
154
155
Enhanced checkbox and radio button controls with theming.
156
157
```javascript { .api }
158
/**
159
* Creates a checkboxradio widget
160
* @param {CheckboxradioOptions} options - Configuration options
161
*/
162
$(...).checkboxradio(options);
163
164
/**
165
* Refreshes the widget's visual state
166
*/
167
$(...).checkboxradio('refresh');
168
169
interface CheckboxradioOptions {
170
classes?: object; // CSS classes to apply
171
disabled?: boolean; // Disable the control
172
icon?: boolean; // Whether to show icon
173
label?: string; // Label text
174
}
175
```
176
177
### Controlgroup
178
179
Groups related form controls with unified styling.
180
181
```javascript { .api }
182
/**
183
* Creates a controlgroup widget
184
* @param {ControlgroupOptions} options - Configuration options
185
*/
186
$(...).controlgroup(options);
187
188
/**
189
* Refreshes the control group layout
190
*/
191
$(...).controlgroup('refresh');
192
193
interface ControlgroupOptions {
194
classes?: object; // CSS classes to apply
195
direction?: 'horizontal' | 'vertical'; // Layout direction
196
disabled?: boolean; // Disable all controls
197
items?: object; // Control type definitions
198
}
199
```
200
201
### Datepicker
202
203
Calendar widget for date selection (not widget-factory based).
204
205
```javascript { .api }
206
/**
207
* Creates a datepicker on an input element
208
* @param {DatepickerOptions} options - Configuration options
209
*/
210
$(...).datepicker(options);
211
212
/**
213
* Sets default datepicker options globally
214
* @param {DatepickerOptions} settings - Default settings
215
*/
216
$.datepicker.setDefaults(settings);
217
218
/**
219
* Formats a date object to string
220
* @param {string} format - Date format string
221
* @param {Date} date - Date to format
222
* @param {object} settings - Additional settings
223
* @returns {string} Formatted date string
224
*/
225
$.datepicker.formatDate(format, date, settings);
226
227
/**
228
* Parses a date string to Date object
229
* @param {string} format - Expected date format
230
* @param {string} value - Date string to parse
231
* @param {object} settings - Additional settings
232
* @returns {Date} Parsed Date object
233
*/
234
$.datepicker.parseDate(format, value, settings);
235
236
interface DatepickerOptions {
237
altField?: string; // Alternative field to update
238
altFormat?: string; // Alternative field date format
239
autoSize?: boolean; // Auto-resize input field
240
buttonImage?: string; // Button image URL
241
buttonImageOnly?: boolean; // Show only image, not button
242
buttonText?: string; // Button text
243
changeMonth?: boolean; // Show month dropdown
244
changeYear?: boolean; // Show year dropdown
245
closeText?: string; // Close button text
246
constrainInput?: boolean; // Constrain input to date format
247
currentText?: string; // Current day button text
248
dateFormat?: string; // Date format string
249
dayNames?: string[]; // Day names array
250
dayNamesMin?: string[]; // Minimum day names array
251
dayNamesShort?: string[]; // Short day names array
252
defaultDate?: Date | number | string; // Default date to highlight
253
duration?: string | number; // Animation duration
254
firstDay?: number; // First day of week (0=Sunday)
255
gotoCurrent?: boolean; // Go to current date
256
hideIfNoPrevNext?: boolean; // Hide prev/next if not applicable
257
isRTL?: boolean; // Right-to-left reading
258
maxDate?: Date | number | string; // Maximum selectable date
259
minDate?: Date | number | string; // Minimum selectable date
260
monthNames?: string[]; // Month names array
261
monthNamesShort?: string[]; // Short month names array
262
navigationAsDateFormat?: boolean; // Format navigation as dates
263
nextText?: string; // Next month button text
264
numberOfMonths?: number | number[]; // Number of months to show
265
prevText?: string; // Previous month button text
266
selectOtherMonths?: boolean; // Allow selection of other months
267
shortYearCutoff?: number | string; // Cutoff for short year format
268
showAnim?: string; // Animation name
269
showButtonPanel?: boolean; // Show button panel
270
showCurrentAtPos?: number; // Position of current month
271
showMonthAfterYear?: boolean; // Show month after year
272
showOn?: 'focus' | 'button' | 'both'; // When to show datepicker
273
showOptions?: object; // Animation options
274
showOtherMonths?: boolean; // Show other months
275
showWeek?: boolean; // Show week numbers
276
stepMonths?: number; // Months to step
277
weekHeader?: string; // Week header text
278
yearRange?: string; // Year range for dropdown
279
yearSuffix?: string; // Year suffix text
280
beforeShow?: (input, inst) => object; // Callback before showing
281
beforeShowDay?: (date) => [boolean, string]; // Callback for each day
282
onChangeMonthYear?: (year, month, inst) => void; // Month/year change callback
283
onClose?: (dateText, inst) => void; // Close callback
284
onSelect?: (dateText, inst) => void; // Selection callback
285
}
286
```
287
288
### Dialog
289
290
Modal and non-modal dialog boxes.
291
292
```javascript { .api }
293
/**
294
* Creates a dialog widget
295
* @param {DialogOptions} options - Configuration options
296
*/
297
$(...).dialog(options);
298
299
/**
300
* Closes the dialog
301
*/
302
$(...).dialog('close');
303
304
/**
305
* Checks if dialog is open
306
* @returns {boolean} True if dialog is open
307
*/
308
$(...).dialog('isOpen');
309
310
/**
311
* Moves dialog to top of z-index stack
312
*/
313
$(...).dialog('moveToTop');
314
315
/**
316
* Opens the dialog
317
*/
318
$(...).dialog('open');
319
320
interface DialogOptions {
321
appendTo?: string; // Element to append dialog to
322
autoOpen?: boolean; // Open automatically on creation
323
buttons?: object | Array; // Button configuration
324
classes?: object; // CSS classes to apply
325
closeOnEscape?: boolean; // Close on Escape key
326
closeText?: string; // Close button text
327
draggable?: boolean; // Enable dragging
328
height?: number | string; // Dialog height
329
hide?: boolean | number | string | object; // Hide animation
330
maxHeight?: number; // Maximum height
331
maxWidth?: number; // Maximum width
332
minHeight?: number; // Minimum height
333
minWidth?: number; // Minimum width
334
modal?: boolean; // Modal dialog
335
position?: object; // Position options
336
resizable?: boolean; // Enable resizing
337
show?: boolean | number | string | object; // Show animation
338
title?: string; // Dialog title
339
width?: number | string; // Dialog width
340
}
341
```
342
343
**Events:**
344
- `dialogbeforeClose` - Triggered before dialog closes
345
- `dialogclose` - Triggered when dialog closes
346
- `dialogcreate` - Triggered when dialog is created
347
- `dialogdrag` - Triggered during drag
348
- `dialogdragStart` - Triggered when drag starts
349
- `dialogdragStop` - Triggered when drag stops
350
- `dialogfocus` - Triggered when dialog gains focus
351
- `dialogopen` - Triggered when dialog opens
352
- `dialogresize` - Triggered during resize
353
- `dialogresizeStart` - Triggered when resize starts
354
- `dialogresizeStop` - Triggered when resize stops
355
356
### Menu
357
358
Hierarchical menu with keyboard navigation support.
359
360
```javascript { .api }
361
/**
362
* Creates a menu widget
363
* @param {MenuOptions} options - Configuration options
364
*/
365
$(...).menu(options);
366
367
/**
368
* Removes focus from menu
369
* @param {Event} event - Original event
370
*/
371
$(...).menu('blur', event);
372
373
/**
374
* Collapses active submenu
375
* @param {Event} event - Original event
376
*/
377
$(...).menu('collapse', event);
378
379
/**
380
* Collapses all open submenus
381
* @param {Event} event - Original event
382
* @param {boolean} all - Whether to collapse all levels
383
*/
384
$(...).menu('collapseAll', event, all);
385
386
/**
387
* Expands submenu under active item
388
* @param {Event} event - Original event
389
*/
390
$(...).menu('expand', event);
391
392
/**
393
* Sets focus to specified menu item
394
* @param {Event} event - Original event
395
* @param {jQuery} item - Menu item to focus
396
*/
397
$(...).menu('focus', event, item);
398
399
/**
400
* Checks if focused item is first in menu
401
* @returns {boolean} True if first item
402
*/
403
$(...).menu('isFirstItem');
404
405
/**
406
* Checks if focused item is last in menu
407
* @returns {boolean} True if last item
408
*/
409
$(...).menu('isLastItem');
410
411
/**
412
* Moves focus to next menu item
413
* @param {Event} event - Original event
414
*/
415
$(...).menu('next', event);
416
417
/**
418
* Moves focus to next page of items
419
* @param {Event} event - Original event
420
*/
421
$(...).menu('nextPage', event);
422
423
/**
424
* Moves focus to previous menu item
425
* @param {Event} event - Original event
426
*/
427
$(...).menu('previous', event);
428
429
/**
430
* Moves focus to previous page of items
431
* @param {Event} event - Original event
432
*/
433
$(...).menu('previousPage', event);
434
435
/**
436
* Refreshes menu structure and submenus
437
*/
438
$(...).menu('refresh');
439
440
/**
441
* Selects currently active menu item
442
* @param {Event} event - Original event
443
*/
444
$(...).menu('select', event);
445
446
interface MenuOptions {
447
classes?: object; // CSS classes to apply
448
disabled?: boolean; // Disable the menu
449
icons?: { // Icon configuration
450
submenu?: string; // Submenu indicator icon
451
};
452
items?: string; // Selector for menu items
453
menus?: string; // Selector for submenus
454
position?: object; // Position options for submenus
455
role?: string; // ARIA role for menu
456
}
457
```
458
459
**Events:**
460
- `menublur` - Triggered when menu loses focus
461
- `menucreate` - Triggered when menu is created
462
- `menufocus` - Triggered when menu item receives focus
463
- `menuselect` - Triggered when menu item is selected
464
465
### Progressbar
466
467
Progress indicator bar showing completion status.
468
469
```javascript { .api }
470
/**
471
* Creates a progressbar widget
472
* @param {ProgressbarOptions} options - Configuration options
473
*/
474
$(...).progressbar(options);
475
476
/**
477
* Gets current progress value
478
* @returns {number} Current value
479
*/
480
$(...).progressbar('value');
481
482
/**
483
* Sets progress value
484
* @param {number} value - New progress value
485
*/
486
$(...).progressbar('value', value);
487
488
interface ProgressbarOptions {
489
classes?: object; // CSS classes to apply
490
disabled?: boolean; // Disable the progressbar
491
max?: number; // Maximum value (default: 100)
492
value?: number; // Current value (default: 0)
493
}
494
```
495
496
**Events:**
497
- `progressbarchange` - Triggered when value changes
498
- `progressbarcomplete` - Triggered when value reaches maximum
499
- `progressbarcreate` - Triggered when progressbar is created
500
501
### Selectmenu
502
503
Customizable replacement for HTML select elements.
504
505
```javascript { .api }
506
/**
507
* Creates a selectmenu widget
508
* @param {SelectmenuOptions} options - Configuration options
509
*/
510
$(...).selectmenu(options);
511
512
/**
513
* Closes the selectmenu dropdown
514
*/
515
$(...).selectmenu('close');
516
517
/**
518
* Returns the menu widget instance
519
* @returns {jQuery} Menu widget
520
*/
521
$(...).selectmenu('menuWidget');
522
523
/**
524
* Opens the selectmenu dropdown
525
*/
526
$(...).selectmenu('open');
527
528
/**
529
* Refreshes options from underlying select element
530
*/
531
$(...).selectmenu('refresh');
532
533
interface SelectmenuOptions {
534
appendTo?: string; // Element to append menu to
535
classes?: object; // CSS classes to apply
536
disabled?: boolean; // Disable the selectmenu
537
icons?: { // Icon configuration
538
button?: string; // Button icon
539
};
540
position?: object; // Position options for menu
541
width?: number | string; // Menu width
542
}
543
```
544
545
**Events:**
546
- `selectmenuchange` - Triggered when selection changes
547
- `selectmenuclose` - Triggered when menu closes
548
- `selectmenucreate` - Triggered when selectmenu is created
549
- `selectmenufocus` - Triggered when menu item receives focus
550
- `selectmenuopen` - Triggered when menu opens
551
- `selectmenuselect` - Triggered when menu item is selected
552
553
### Slider
554
555
Range input control with draggable handles.
556
557
```javascript { .api }
558
/**
559
* Creates a slider widget
560
* @param {SliderOptions} options - Configuration options
561
*/
562
$(...).slider(options);
563
564
/**
565
* Gets current value (single handle slider)
566
* @returns {number} Current value
567
*/
568
$(...).slider('value');
569
570
/**
571
* Sets value (single handle slider)
572
* @param {number} value - New value
573
*/
574
$(...).slider('value', value);
575
576
/**
577
* Gets all values (multi-handle slider)
578
* @returns {number[]} Array of values
579
*/
580
$(...).slider('values');
581
582
/**
583
* Gets value at specific index (multi-handle slider)
584
* @param {number} index - Handle index
585
* @returns {number} Value at index
586
*/
587
$(...).slider('values', index);
588
589
/**
590
* Sets value at specific index (multi-handle slider)
591
* @param {number} index - Handle index
592
* @param {number} value - New value
593
*/
594
$(...).slider('values', index, value);
595
596
/**
597
* Sets all values (multi-handle slider)
598
* @param {number[]} values - Array of new values
599
*/
600
$(...).slider('values', values);
601
602
interface SliderOptions {
603
animate?: boolean | string | number; // Animation settings
604
classes?: object; // CSS classes to apply
605
disabled?: boolean; // Disable the slider
606
max?: number; // Maximum value
607
min?: number; // Minimum value
608
orientation?: 'horizontal' | 'vertical'; // Slider orientation
609
range?: boolean | 'min' | 'max'; // Range display
610
step?: number; // Step size
611
value?: number; // Initial value (single handle)
612
values?: number[]; // Initial values (multi-handle)
613
}
614
```
615
616
**Events:**
617
- `slidechange` - Triggered when value changes
618
- `slidecreate` - Triggered when slider is created
619
- `slide` - Triggered during sliding
620
- `slidestart` - Triggered when sliding starts
621
- `slidestop` - Triggered when sliding stops
622
623
### Spinner
624
625
Numeric input with increment/decrement buttons.
626
627
```javascript { .api }
628
/**
629
* Creates a spinner widget
630
* @param {SpinnerOptions} options - Configuration options
631
*/
632
$(...).spinner(options);
633
634
/**
635
* Decrements value by page amount
636
* @param {number} pages - Number of pages to decrement
637
*/
638
$(...).spinner('pageDown', pages);
639
640
/**
641
* Increments value by page amount
642
* @param {number} pages - Number of pages to increment
643
*/
644
$(...).spinner('pageUp', pages);
645
646
/**
647
* Decrements value by step amount
648
* @param {number} steps - Number of steps to decrement
649
*/
650
$(...).spinner('stepDown', steps);
651
652
/**
653
* Increments value by step amount
654
* @param {number} steps - Number of steps to increment
655
*/
656
$(...).spinner('stepUp', steps);
657
658
/**
659
* Gets current numeric value
660
* @returns {number} Current value
661
*/
662
$(...).spinner('value');
663
664
/**
665
* Sets numeric value
666
* @param {number} value - New value
667
*/
668
$(...).spinner('value', value);
669
670
interface SpinnerOptions {
671
classes?: object; // CSS classes to apply
672
culture?: string; // Culture for number formatting
673
disabled?: boolean; // Disable the spinner
674
icons?: { // Icon configuration
675
down?: string; // Down button icon
676
up?: string; // Up button icon
677
};
678
incremental?: boolean | Function; // Incremental spinning behavior
679
max?: number; // Maximum value
680
min?: number; // Minimum value
681
numberFormat?: string; // Number format string
682
page?: number; // Page increment size
683
step?: number; // Step increment size
684
}
685
```
686
687
**Events:**
688
- `spinchange` - Triggered when value changes
689
- `spincreate` - Triggered when spinner is created
690
- `spin` - Triggered during spinning
691
- `spinstart` - Triggered when spinning starts
692
- `spinstop` - Triggered when spinning stops
693
694
### Tabs
695
696
Tabbed interface for organizing content into panels.
697
698
```javascript { .api }
699
/**
700
* Creates a tabs widget
701
* @param {TabsOptions} options - Configuration options
702
*/
703
$(...).tabs(options);
704
705
/**
706
* Disables specified tab by index
707
* @param {number} index - Tab index to disable
708
*/
709
$(...).tabs('disable', index);
710
711
/**
712
* Enables specified tab by index
713
* @param {number} index - Tab index to enable
714
*/
715
$(...).tabs('enable', index);
716
717
/**
718
* Loads tab content via AJAX
719
* @param {number} index - Tab index to load
720
*/
721
$(...).tabs('load', index);
722
723
/**
724
* Processes added/removed tabs and refreshes
725
*/
726
$(...).tabs('refresh');
727
728
interface TabsOptions {
729
active?: number | boolean; // Initially active tab
730
classes?: object; // CSS classes to apply
731
collapsible?: boolean; // Allow active tab to be deselected
732
disabled?: boolean | number[]; // Disabled tabs
733
event?: string; // Event that activates tab
734
heightStyle?: 'auto' | 'fill' | 'content'; // Height calculation
735
hide?: boolean | number | string | object; // Hide animation
736
show?: boolean | number | string | object; // Show animation
737
}
738
```
739
740
**Events:**
741
- `tabsactivate` - Triggered after tab is activated
742
- `tabsbeforeActivate` - Triggered before tab is activated
743
- `tabsbeforeLoad` - Triggered before AJAX tab load
744
- `tabscreate` - Triggered when tabs widget is created
745
- `tabsload` - Triggered after AJAX tab load completes
746
747
### Tooltip
748
749
Customizable tooltip replacement for title attribute.
750
751
```javascript { .api }
752
/**
753
* Creates a tooltip widget
754
* @param {TooltipOptions} options - Configuration options
755
*/
756
$(...).tooltip(options);
757
758
/**
759
* Closes tooltip programmatically
760
* @param {Event} event - Original event
761
*/
762
$(...).tooltip('close', event);
763
764
/**
765
* Opens tooltip programmatically
766
* @param {Event} event - Original event
767
*/
768
$(...).tooltip('open', event);
769
770
interface TooltipOptions {
771
classes?: object; // CSS classes to apply
772
content?: string | Function; // Tooltip content
773
disabled?: boolean; // Disable the tooltip
774
hide?: boolean | number | string | object; // Hide animation
775
items?: string; // Selector for elements with tooltips
776
position?: object; // Position options
777
show?: boolean | number | string | object; // Show animation
778
tooltipClass?: string; // Additional CSS class for tooltip
779
track?: boolean; // Track mouse movement
780
}
781
```
782
783
**Events:**
784
- `tooltipclose` - Triggered when tooltip closes
785
- `tooltipcreate` - Triggered when tooltip is created
786
- `tooltipopen` - Triggered when tooltip opens
787
788
## Types
789
790
```javascript { .api }
791
// Common widget event object
792
interface WidgetEvent {
793
type: string;
794
target: Element;
795
currentTarget: Element;
796
originalEvent?: Event;
797
data?: any;
798
}
799
800
// Base widget options (inherited by all widgets)
801
interface BaseWidgetOptions {
802
disabled?: boolean;
803
classes?: { [key: string]: string };
804
}
805
806
// Widget method return types
807
type WidgetMethodReturn = jQuery | any;
808
809
// Animation options (used by multiple widgets)
810
interface AnimationOptions {
811
effect?: string;
812
duration?: number | string;
813
easing?: string;
814
complete?: () => void;
815
}
816
```