0
# Form Controls
1

2
Interactive form elements with full accessibility support including labels, validation, error messaging, and keyboard navigation. All form controls provide ARIA attributes, label association, and proper focus management.
3

4
## Capabilities
5

6
### Button
7

8
Provides button behavior including press handling, keyboard navigation, and accessibility attributes.
9

10
```typescript { .api }
11
/**
12
 * Provides button behavior and accessibility
13
 * @param props - Button configuration options
14
 * @param ref - Ref to the button element
15
 * @returns Button props and state
16
 */
17
function useButton(props: AriaButtonProps, ref: RefObject<Element>): ButtonAria;
18

19
interface AriaButtonProps {
20
  /** Whether the button is disabled */
21
  isDisabled?: boolean;
22
  /** Handler called when the button is pressed */
23
  onPress?: (e: PressEvent) => void;
24
  /** Handler called when a press interaction starts */
25
  onPressStart?: (e: PressEvent) => void;
26
  /** Handler called when a press interaction ends */
27
  onPressEnd?: (e: PressEvent) => void;
28
  /** Handler called when the press is released over the target */
29
  onPressUp?: (e: PressEvent) => void;
30
  /** Handler called when a press interaction changes */
31
  onPressChange?: (isPressed: boolean) => void;
32
  /** Whether press events should be disabled */
33
  preventFocusOnPress?: boolean;
34
  /** Whether the button should receive focus on press (mobile) */
35
  shouldCancelOnPointerExit?: boolean;
36
  /** Text description of the button for accessibility */
37
  'aria-label'?: string;
38
  /** ID of element that labels the button */
39
  'aria-labelledby'?: string;
40
  /** ID of element that describes the button */
41
  'aria-describedby'?: string;
42
}
43

44
interface ButtonAria {
45
  /** Props to spread on the button element */
46
  buttonProps: DOMAttributes<Element>;
47
  /** Whether the button is currently pressed */
48
  isPressed: boolean;
49
}
50
```
51

52
**Usage Example:**
53

54
```typescript
55
import { useButton } from "react-aria";
56

57
function Button(props) {
58
  let ref = useRef();
59
  let { buttonProps, isPressed } = useButton(props, ref);
60

61
  return (
62
    <button
63
      {...buttonProps}
64
      ref={ref}
65
      className={`button ${isPressed ? 'pressed' : ''}`}
66
    >
67
      {props.children}
68
    </button>
69
  );
70
}
71
```
72

73
### Toggle Button
74

75
Provides toggle button behavior with pressed state management.
76

77
```typescript { .api }
78
/**
79
 * Provides toggle button behavior and accessibility
80
 * @param props - Toggle button configuration
81
 * @param ref - Ref to the button element
82
 * @returns Toggle button props and state
83
 */
84
function useToggleButton(props: AriaToggleButtonProps, ref: RefObject<Element>): ButtonAria;
85

86
interface AriaToggleButtonProps extends AriaButtonProps {
87
  /** Whether the button is selected (pressed) */
88
  isSelected?: boolean;
89
  /** Handler called when the button's selection state changes */
90
  onChange?: (isSelected: boolean) => void;
91
}
92
```
93

94
### Toggle Button Group
95

96
Manages a group of toggle buttons with optional single or multiple selection.
97

98
```typescript { .api }
99
/**
100
 * Provides toggle button group behavior
101
 * @param props - Toggle button group configuration
102
 * @param ref - Ref to the group element
103
 * @returns Toggle button group props
104
 */
105
function useToggleButtonGroup(props: AriaToggleButtonGroupProps, ref: RefObject<Element>): ToggleButtonGroupAria;
106

107
/**
108
 * Provides individual toggle button behavior within a group
109
 * @param props - Toggle button item configuration
110
 * @param state - Toggle button group state
111
 * @param ref - Ref to the button element
112
 * @returns Toggle button item props
113
 */
114
function useToggleButtonGroupItem(props: AriaToggleButtonGroupItemProps, state: ToggleButtonGroupState, ref: RefObject<Element>): ButtonAria;
115

116
interface AriaToggleButtonGroupProps {
117
  /** Whether multiple buttons can be selected */
118
  selectionMode?: 'single' | 'multiple';
119
  /** Currently selected keys */
120
  selectedKeys?: Iterable<Key>;
121
  /** Default selected keys (uncontrolled) */
122
  defaultSelectedKeys?: Iterable<Key>;
123
  /** Handler called when selection changes */
124
  onSelectionChange?: (keys: Set<Key>) => void;
125
  /** Whether the group is disabled */
126
  isDisabled?: boolean;
127
  /** Orientation of the button group */
128
  orientation?: Orientation;
129
}
130
```
131

132
### Text Field
133

134
Provides text input behavior with label association, validation, and accessibility.
135

136
```typescript { .api }
137
/**
138
 * Provides text field behavior and accessibility
139
 * @param props - Text field configuration
140
 * @param ref - Ref to the input element
141
 * @returns Text field props and state
142
 */
143
function useTextField(props: AriaTextFieldProps, ref: RefObject<Element>): TextFieldAria;
144

145
interface AriaTextFieldProps extends AriaTextFieldOptions {
146
  /** Current value of the text field */
147
  value?: string;
148
  /** Default value (uncontrolled) */
149
  defaultValue?: string;
150
  /** Handler called when the value changes */
151
  onChange?: (value: string) => void;
152
  /** Placeholder text */
153
  placeholder?: string;
154
  /** Whether the field is disabled */
155
  isDisabled?: boolean;
156
  /** Whether the field is read-only */
157
  isReadOnly?: boolean;
158
  /** Whether the field is required */
159
  isRequired?: boolean;
160
  /** Type of validation state */
161
  validationState?: 'valid' | 'invalid';
162
  /** Auto-complete hint */
163
  autoComplete?: string;
164
  /** Maximum number of characters */
165
  maxLength?: number;
166
  /** Minimum number of characters */
167
  minLength?: number;
168
  /** Pattern for validation */
169
  pattern?: string;
170
  /** Input type */
171
  type?: 'text' | 'search' | 'url' | 'tel' | 'email' | 'password';
172
  /** Input mode */
173
  inputMode?: 'none' | 'text' | 'tel' | 'url' | 'email' | 'numeric' | 'decimal' | 'search';
174
}
175

176
interface TextFieldAria {
177
  /** Props for the text field label element */
178
  labelProps: DOMAttributes<Element>;
179
  /** Props for the input element */
180
  inputProps: InputHTMLAttributes<HTMLInputElement>;
181
  /** Props for the description element */
182
  descriptionProps: DOMAttributes<Element>;
183
  /** Props for the error message element */
184
  errorMessageProps: DOMAttributes<Element>;
185
}
186
```
187

188
### Checkbox
189

190
Provides checkbox behavior with tri-state support and group management.
191

192
```typescript { .api }
193
/**
194
 * Provides checkbox behavior and accessibility
195
 * @param props - Checkbox configuration
196
 * @param ref - Ref to the input element
197
 * @returns Checkbox props and state
198
 */
199
function useCheckbox(props: AriaCheckboxProps, ref: RefObject<Element>): CheckboxAria;
200

201
interface AriaCheckboxProps {
202
  /** Whether the checkbox is selected */
203
  isSelected?: boolean;
204
  /** Default selection state (uncontrolled) */
205
  defaultSelected?: boolean;
206
  /** Whether the checkbox is in an indeterminate state */
207
  isIndeterminate?: boolean;
208
  /** Whether the checkbox is disabled */
209
  isDisabled?: boolean;
210
  /** Whether the checkbox is read-only */
211
  isReadOnly?: boolean;
212
  /** Handler called when selection changes */
213
  onChange?: (isSelected: boolean) => void;
214
  /** Value of the checkbox */
215
  value?: string;
216
  /** Name of the checkbox (for forms) */
217
  name?: string;
218
  /** The checkbox's validation state */
219
  validationState?: 'valid' | 'invalid';
220
  /** Whether the checkbox is required */
221
  isRequired?: boolean;
222
}
223

224
interface CheckboxAria {
225
  /** Props for the input element */
226
  inputProps: InputHTMLAttributes<HTMLInputElement>;
227
  /** Props for the label wrapper */
228
  labelProps: LabelHTMLAttributes<HTMLLabelElement>;
229
  /** Whether the checkbox is selected */
230
  isSelected: boolean;
231
  /** Whether the checkbox is in an invalid state */
232
  isInvalid: boolean;
233
  /** Whether the checkbox is disabled */
234
  isDisabled: boolean;
235
  /** Whether the checkbox is read-only */
236
  isReadOnly: boolean;
237
  /** Whether the checkbox is required */
238
  isRequired: boolean;
239
  /** Whether the checkbox is pressed */
240
  isPressed: boolean;
241
}
242
```
243

244
### Checkbox Group
245

246
Manages a group of checkboxes with shared validation and labeling.
247

248
```typescript { .api }
249
/**
250
 * Provides checkbox group behavior
251
 * @param props - Checkbox group configuration
252
 * @param ref - Ref to the group element
253
 * @returns Checkbox group props and state
254
 */
255
function useCheckboxGroup(props: AriaCheckboxGroupProps, ref: RefObject<Element>): CheckboxGroupAria;
256

257
/**
258
 * Provides individual checkbox behavior within a group
259
 * @param props - Checkbox configuration within group
260
 * @param state - Checkbox group state
261
 * @param ref - Ref to the input element
262
 * @returns Checkbox props for group item
263
 */
264
function useCheckboxGroupItem(props: AriaCheckboxGroupItemProps, state: CheckboxGroupState, ref: RefObject<Element>): CheckboxAria;
265

266
interface AriaCheckboxGroupProps {
267
  /** Currently selected values */
268
  value?: string[];
269
  /** Default selected values (uncontrolled) */
270
  defaultValue?: string[];
271
  /** Handler called when selection changes */
272
  onChange?: (value: string[]) => void;
273
  /** Whether the group is disabled */
274
  isDisabled?: boolean;
275
  /** Whether the group is read-only */
276
  isReadOnly?: boolean;
277
  /** Whether the group is required */
278
  isRequired?: boolean;
279
  /** Validation state of the group */
280
  validationState?: 'valid' | 'invalid';
281
  /** Name for the checkbox group */
282
  name?: string;
283
  /** Label for the group */
284
  label?: ReactNode;
285
  /** Description for the group */
286
  description?: ReactNode;
287
  /** Error message for the group */
288
  errorMessage?: ReactNode;
289
}
290
```
291

292
### Radio Button
293

294
Provides radio button behavior with group management and keyboard navigation.
295

296
```typescript { .api }
297
/**
298
 * Provides radio button behavior and accessibility
299
 * @param props - Radio button configuration
300
 * @param ref - Ref to the input element
301
 * @returns Radio button props and state
302
 */
303
function useRadio(props: AriaRadioProps, ref: RefObject<Element>): RadioAria;
304

305
/**
306
 * Provides radio group behavior
307
 * @param props - Radio group configuration
308
 * @param ref - Ref to the group element
309
 * @returns Radio group props and state
310
 */
311
function useRadioGroup(props: AriaRadioGroupProps, ref: RefObject<Element>): RadioGroupAria;
312

313
interface AriaRadioProps {
314
  /** Value of the radio button */
315
  value: string;
316
  /** Whether the radio is disabled */
317
  isDisabled?: boolean;
318
  /** Whether the radio is required */
319
  isRequired?: boolean;
320
  /** Validation state */
321
  validationState?: 'valid' | 'invalid';
322
}
323

324
interface AriaRadioGroupProps {
325
  /** Currently selected value */
326
  value?: string;
327
  /** Default selected value (uncontrolled) */
328
  defaultValue?: string;
329
  /** Handler called when selection changes */
330
  onChange?: (value: string) => void;
331
  /** Whether the group is disabled */
332
  isDisabled?: boolean;
333
  /** Whether the group is read-only */
334
  isReadOnly?: boolean;
335
  /** Whether the group is required */
336
  isRequired?: boolean;
337
  /** Validation state of the group */
338
  validationState?: 'valid' | 'invalid';
339
  /** Name for the radio group */
340
  name?: string;
341
  /** Label for the group */
342
  label?: ReactNode;
343
  /** Description for the group */
344
  description?: ReactNode;
345
  /** Error message for the group */
346
  errorMessage?: ReactNode;
347
  /** Orientation of the radio buttons */
348
  orientation?: Orientation;
349
}
350
```
351

352
### Switch
353

354
Provides switch/toggle behavior similar to checkbox but with different semantics.
355

356
```typescript { .api }
357
/**
358
 * Provides switch behavior and accessibility
359
 * @param props - Switch configuration
360
 * @param ref - Ref to the input element
361
 * @returns Switch props and state
362
 */
363
function useSwitch(props: AriaSwitchProps, ref: RefObject<Element>): SwitchAria;
364

365
interface AriaSwitchProps {
366
  /** Whether the switch is selected */
367
  isSelected?: boolean;
368
  /** Default selection state (uncontrolled) */
369
  defaultSelected?: boolean;
370
  /** Whether the switch is disabled */
371
  isDisabled?: boolean;
372
  /** Whether the switch is read-only */
373
  isReadOnly?: boolean;
374
  /** Handler called when selection changes */
375
  onChange?: (isSelected: boolean) => void;
376
  /** Value of the switch */
377
  value?: string;
378
  /** Name of the switch (for forms) */
379
  name?: string;
380
  /** The switch's validation state */
381
  validationState?: 'valid' | 'invalid';
382
}
383

384
interface SwitchAria {
385
  /** Props for the input element */
386
  inputProps: InputHTMLAttributes<HTMLInputElement>;
387
  /** Props for the label wrapper */
388
  labelProps: LabelHTMLAttributes<HTMLLabelElement>;
389
  /** Whether the switch is selected */
390
  isSelected: boolean;
391
  /** Whether the switch is disabled */
392
  isDisabled: boolean;
393
  /** Whether the switch is read-only */
394
  isReadOnly: boolean;
395
  /** Whether the switch is pressed */
396
  isPressed: boolean;
397
}
398
```
399

400
### Number Field
401

402
Provides numeric input with increment/decrement controls and validation.
403

404
```typescript { .api }
405
/**
406
 * Provides number field behavior and accessibility
407
 * @param props - Number field configuration
408
 * @param ref - Ref to the input element
409
 * @returns Number field props and state
410
 */
411
function useNumberField(props: AriaNumberFieldProps, ref: RefObject<Element>): NumberFieldAria;
412

413
interface AriaNumberFieldProps {
414
  /** Current numeric value */
415
  value?: number;
416
  /** Default value (uncontrolled) */
417
  defaultValue?: number;
418
  /** Handler called when value changes */
419
  onChange?: (value: number) => void;
420
  /** Minimum allowed value */
421
  minValue?: number;
422
  /** Maximum allowed value */
423
  maxValue?: number;
424
  /** Amount to increment/decrement */
425
  step?: number;
426
  /** Whether the field is disabled */
427
  isDisabled?: boolean;
428
  /** Whether the field is read-only */
429
  isReadOnly?: boolean;
430
  /** Whether the field is required */
431
  isRequired?: boolean;
432
  /** Number formatting options */
433
  formatOptions?: Intl.NumberFormatOptions;
434
  /** Validation state */
435
  validationState?: 'valid' | 'invalid';
436
}
437

438
interface NumberFieldAria {
439
  /** Props for the label element */
440
  labelProps: DOMAttributes<Element>;
441
  /** Props for the number input element */
442
  inputProps: InputHTMLAttributes<HTMLInputElement>;
443
  /** Props for the increment button */
444
  incrementButtonProps: ButtonHTMLAttributes<HTMLButtonElement>;
445
  /** Props for the decrement button */
446
  decrementButtonProps: ButtonHTMLAttributes<HTMLButtonElement>;
447
  /** Props for the description element */
448
  descriptionProps: DOMAttributes<Element>;
449
  /** Props for the error message element */
450
  errorMessageProps: DOMAttributes<Element>;
451
}
452
```
453

454
### Search Field
455

456
Provides search input behavior with clear button and search semantics.
457

458
```typescript { .api }
459
/**
460
 * Provides search field behavior and accessibility
461
 * @param props - Search field configuration
462
 * @param ref - Ref to the input element
463
 * @returns Search field props and state
464
 */
465
function useSearchField(props: AriaSearchFieldProps, ref: RefObject<Element>): SearchFieldAria;
466

467
interface AriaSearchFieldProps extends AriaTextFieldProps {
468
  /** Handler called when the search is submitted */
469
  onSubmit?: (value: string) => void;
470
  /** Handler called when the clear button is pressed */
471
  onClear?: () => void;
472
}
473

474
interface SearchFieldAria extends TextFieldAria {
475
  /** Props for the clear button */
476
  clearButtonProps: ButtonHTMLAttributes<HTMLButtonElement>;
477
}
478
```
479

480
### Color Components
481

482
Specialized form controls for color selection and editing with full accessibility support.
483

484
```typescript { .api }
485
/**
486
 * Provides color area behavior for 2D color selection
487
 * @param props - Color area configuration
488
 * @param ref - Ref to the color area element
489
 * @returns Color area props and state
490
 */
491
function useColorArea(props: AriaColorAreaProps, ref: RefObject<Element>): ColorAreaAria;
492

493
/**
494
 * Provides color channel field behavior for individual color channels
495
 * @param props - Color channel field configuration
496
 * @param ref - Ref to the input element
497
 * @returns Color channel field props and state
498
 */
499
function useColorChannelField(props: AriaColorChannelFieldProps, ref: RefObject<Element>): ColorChannelFieldAria;
500

501
/**
502
 * Provides color field behavior for color input
503
 * @param props - Color field configuration
504
 * @param ref - Ref to the input element
505
 * @returns Color field props and state
506
 */
507
function useColorField(props: AriaColorFieldProps, ref: RefObject<Element>): ColorFieldAria;
508

509
/**
510
 * Provides color slider behavior for color channel sliders
511
 * @param props - Color slider configuration
512
 * @param ref - Ref to the slider element
513
 * @returns Color slider props and state
514
 */
515
function useColorSlider(props: AriaColorSliderProps, ref: RefObject<Element>): ColorSliderAria;
516

517
/**
518
 * Provides color swatch behavior for color preview
519
 * @param props - Color swatch configuration
520
 * @param ref - Ref to the swatch element
521
 * @returns Color swatch props and state
522
 */
523
function useColorSwatch(props: AriaColorSwatchProps, ref: RefObject<Element>): ColorSwatchAria;
524

525
/**
526
 * Provides color wheel behavior for hue selection
527
 * @param props - Color wheel configuration
528
 * @param ref - Ref to the color wheel element
529
 * @returns Color wheel props and state
530
 */
531
function useColorWheel(props: AriaColorWheelOptions, ref: RefObject<Element>): ColorWheelAria;
532

533
interface AriaColorAreaProps {
534
  /** Current color value */
535
  value?: Color;
536
  /** Default color value (uncontrolled) */
537
  defaultValue?: Color;
538
  /** Handler called when color changes */
539
  onChange?: (value: Color) => void;
540
  /** Color space and channel for X axis */
541
  xChannel: ColorChannel;
542
  /** Color space and channel for Y axis */
543
  yChannel: ColorChannel;
544
  /** Whether the color area is disabled */
545
  isDisabled?: boolean;
546
  /** Step increment for keyboard navigation */
547
  step?: number;
548
  /** Page step increment for page up/down keys */
549
  pageStep?: number;
550
}
551

552
interface ColorAreaAria {
553
  /** Props for the color area element */
554
  colorAreaProps: DOMAttributes<Element>;
555
  /** Props for the thumb element */
556
  thumbProps: DOMAttributes<Element>;
557
  /** Whether the thumb is being dragged */
558
  isDragging: boolean;
559
}
560

561
interface AriaColorChannelFieldProps {
562
  /** Current color value */
563
  value?: Color;
564
  /** Default color value (uncontrolled) */
565
  defaultValue?: Color;
566
  /** Handler called when color changes */
567
  onChange?: (value: Color) => void;
568
  /** Color channel to edit */
569
  channel: ColorChannel;
570
  /** Color space */
571
  colorSpace: ColorSpace;
572
  /** Whether the field is disabled */
573
  isDisabled?: boolean;
574
  /** Whether the field is read-only */
575
  isReadOnly?: boolean;
576
}
577

578
interface ColorChannelFieldAria {
579
  /** Props for the label element */
580
  labelProps: DOMAttributes<Element>;
581
  /** Props for the input element */
582
  inputProps: InputHTMLAttributes<HTMLInputElement>;
583
  /** Props for the increment button */
584
  incrementButtonProps: ButtonHTMLAttributes<HTMLButtonElement>;
585
  /** Props for the decrement button */
586
  decrementButtonProps: ButtonHTMLAttributes<HTMLButtonElement>;
587
}
588

589
interface AriaColorFieldProps {
590
  /** Current color value */
591
  value?: Color;
592
  /** Default color value (uncontrolled) */
593
  defaultValue?: Color;
594
  /** Handler called when color changes */
595
  onChange?: (value: Color) => void;
596
  /** Whether the field is disabled */
597
  isDisabled?: boolean;
598
  /** Whether the field is read-only */
599
  isReadOnly?: boolean;
600
  /** Validation state */
601
  validationState?: 'valid' | 'invalid';
602
}
603

604
interface ColorFieldAria {
605
  /** Props for the label element */
606
  labelProps: DOMAttributes<Element>;
607
  /** Props for the input element */
608
  inputProps: InputHTMLAttributes<HTMLInputElement>;
609
}
610

611
interface AriaColorSliderProps {
612
  /** Current color value */
613
  value?: Color;
614
  /** Default color value (uncontrolled) */
615
  defaultValue?: Color;
616
  /** Handler called when color changes */
617
  onChange?: (value: Color) => void;
618
  /** Color channel to control */
619
  channel: ColorChannel;
620
  /** Color space */
621
  colorSpace: ColorSpace;
622
  /** Orientation of the slider */
623
  orientation?: Orientation;
624
  /** Whether the slider is disabled */
625
  isDisabled?: boolean;
626
  /** Step increment */
627
  step?: number;
628
  /** Page step increment */
629
  pageStep?: number;
630
}
631

632
interface ColorSliderAria {
633
  /** Props for the slider container */
634
  containerProps: DOMAttributes<Element>;
635
  /** Props for the track element */
636
  trackProps: DOMAttributes<Element>;
637
  /** Props for the thumb element */
638
  thumbProps: DOMAttributes<Element>;
639
  /** Props for the output element */
640
  outputProps: DOMAttributes<Element>;
641
  /** Whether the thumb is being dragged */
642
  isDragging: boolean;
643
}
644

645
interface AriaColorSwatchProps {
646
  /** Color to display */
647
  color: Color;
648
  /** Whether the swatch is disabled */
649
  isDisabled?: boolean;
650
}
651

652
interface ColorSwatchAria {
653
  /** Props for the color swatch element */
654
  colorSwatchProps: DOMAttributes<Element>;
655
}
656

657
interface AriaColorWheelOptions {
658
  /** Current color value */
659
  value?: Color;
660
  /** Default color value (uncontrolled) */
661
  defaultValue?: Color;
662
  /** Handler called when color changes */
663
  onChange?: (value: Color) => void;
664
  /** Whether the color wheel is disabled */
665
  isDisabled?: boolean;
666
  /** Step increment for keyboard navigation */
667
  step?: number;
668
  /** Page step increment for page up/down keys */
669
  pageStep?: number;
670
}
671

672
interface ColorWheelAria {
673
  /** Props for the color wheel element */
674
  colorWheelProps: DOMAttributes<Element>;
675
  /** Props for the thumb element */
676
  thumbProps: DOMAttributes<Element>;
677
  /** Whether the thumb is being dragged */
678
  isDragging: boolean;
679
}
680

681
// Color-related types
682
type ColorChannel = 'hue' | 'saturation' | 'brightness' | 'lightness' | 'red' | 'green' | 'blue' | 'alpha';
683
type ColorSpace = 'rgb' | 'hsl' | 'hsb';
684

685
interface Color {
686
  /** Convert to hex string */
687
  toString(format?: 'hex' | 'rgb' | 'hsl' | 'hsb'): string;
688
  /** Get channel value */
689
  getChannelValue(channel: ColorChannel): number;
690
  /** Set channel value */
691
  withChannelValue(channel: ColorChannel, value: number): Color;
692
  /** Get color space */
693
  getColorSpace(): ColorSpace;
694
  /** Convert to color space */
695
  toFormat(format: ColorSpace): Color;
696
}
697
```
698

699
### Progress and Measurement
700

701
Components for displaying progress, metrics, and value ranges.
702

703
```typescript { .api }
704
/**
705
 * Provides progress bar behavior and accessibility
706
 * @param props - Progress bar configuration
707
 * @param ref - Ref to the progress element
708
 * @returns Progress bar props and state
709
 */
710
function useProgressBar(props: AriaProgressBarProps, ref: RefObject<Element>): ProgressBarAria;
711

712
/**
713
 * Provides meter behavior for displaying scalar values
714
 * @param props - Meter configuration
715
 * @param ref - Ref to the meter element
716
 * @returns Meter props and state
717
 */
718
function useMeter(props: AriaMeterProps, ref: RefObject<Element>): MeterAria;
719

720
/**
721
 * Provides slider behavior for selecting values from a range
722
 * @param props - Slider configuration
723
 * @param ref - Ref to the slider element
724
 * @returns Slider props and state
725
 */
726
function useSlider(props: AriaSliderProps, ref: RefObject<Element>): SliderAria;
727

728
/**
729
 * Provides slider thumb behavior for individual slider handles
730
 * @param props - Slider thumb configuration
731
 * @param state - Slider state
732
 * @param ref - Ref to the thumb element
733
 * @returns Slider thumb props and state
734
 */
735
function useSliderThumb(props: AriaSliderThumbProps, state: SliderState, ref: RefObject<Element>): SliderThumbAria;
736

737
interface AriaProgressBarProps {
738
  /** Current progress value */
739
  value?: number;
740
  /** Minimum value */
741
  minValue?: number;
742
  /** Maximum value */
743
  maxValue?: number;
744
  /** Whether progress is indeterminate */
745
  isIndeterminate?: boolean;
746
  /** Format function for value display */
747
  formatOptions?: Intl.NumberFormatOptions;
748
  /** Accessible label */
749
  'aria-label'?: string;
750
  /** ID of element that labels the progress bar */
751
  'aria-labelledby'?: string;
752
}
753

754
interface ProgressBarAria {
755
  /** Props for the progress bar element */
756
  progressBarProps: ProgressHTMLAttributes<HTMLProgressElement>;
757
  /** Props for the label element */
758
  labelProps: DOMAttributes<Element>;
759
}
760

761
interface AriaMeterProps {
762
  /** Current value */
763
  value: number;
764
  /** Minimum value */
765
  minValue?: number;
766
  /** Maximum value */
767
  maxValue?: number;
768
  /** Low threshold value */
769
  low?: number;
770
  /** High threshold value */
771
  high?: number;
772
  /** Optimum value */
773
  optimum?: number;
774
  /** Format function for value display */
775
  formatOptions?: Intl.NumberFormatOptions;
776
}
777

778
interface MeterAria {
779
  /** Props for the meter element */
780
  meterProps: MeterHTMLAttributes<HTMLMeterElement>;
781
  /** Props for the label element */
782
  labelProps: DOMAttributes<Element>;
783
}
784

785
interface AriaSliderProps {
786
  /** Current values */
787
  value?: number | number[];
788
  /** Default values (uncontrolled) */
789
  defaultValue?: number | number[];
790
  /** Handler called when values change */
791
  onChange?: (value: number | number[]) => void;
792
  /** Minimum value */
793
  minValue?: number;
794
  /** Maximum value */
795
  maxValue?: number;
796
  /** Step increment */
797
  step?: number;
798
  /** Page step increment */
799
  pageStep?: number;
800
  /** Orientation of the slider */
801
  orientation?: Orientation;
802
  /** Whether the slider is disabled */
803
  isDisabled?: boolean;
804
  /** Format function for value display */
805
  formatOptions?: Intl.NumberFormatOptions;
806
  /** Whether to show thumb labels */
807
  showValueLabel?: boolean;
808
  /** Function to get thumb label */
809
  getThumbLabel?: (index: number) => string;
810
}
811

812
interface SliderAria {
813
  /** Props for the slider container */
814
  containerProps: DOMAttributes<Element>;
815
  /** Props for the track element */
816
  trackProps: DOMAttributes<Element>;
817
  /** Props for the label element */
818
  labelProps: DOMAttributes<Element>;
819
  /** Props for the output element */
820
  outputProps: DOMAttributes<Element>;
821
}
822

823
interface AriaSliderThumbProps {
824
  /** Index of the thumb */
825
  index: number;
826
  /** Whether the thumb is disabled */
827
  isDisabled?: boolean;
828
  /** Name for form integration */
829
  name?: string;
830
}
831

832
interface SliderThumbAria {
833
  /** Props for the thumb element */
834
  thumbProps: DOMAttributes<Element>;
835
  /** Props for the input element */
836
  inputProps: InputHTMLAttributes<HTMLInputElement>;
837
  /** Whether the thumb is being dragged */
838
  isDragging: boolean;
839
  /** Whether the thumb is focused */
840
  isFocused: boolean;
841
  /** Value of this thumb */
842
  value: number;
843
}
844

845
interface SliderState {
846
  /** Array of thumb values */
847
  values: number[];
848
  /** Get value for thumb index */
849
  getThumbValue(index: number): number;
850
  /** Set value for thumb index */
851
  setThumbValue(index: number, value: number): void;
852
  /** Set dragging state for thumb */
853
  setThumbDragging(index: number, dragging: boolean): void;
854
  /** Whether thumb is being dragged */
855
  isThumbDragging(index: number): boolean;
856
  /** Get percent for value */
857
  getValuePercent(value: number): number;
858
  /** Get value for percent */
859
  getPercentValue(percent: number): number;
860
  /** Get display value */
861
  getDisplayValue(value: number): string;
862
}
863
```
864

865
### Labeling and Fields
866

867
Utilities for form field labeling and accessibility.
868

869
```typescript { .api }
870
/**
871
 * Provides form field behavior and accessibility
872
 * @param props - Field configuration
873
 * @param ref - Ref to the field element
874
 * @returns Field props and state
875
 */
876
function useField(props: AriaFieldProps, ref: RefObject<Element>): FieldAria;
877

878
/**
879
 * Provides label behavior and accessibility
880
 * @param props - Label configuration
881
 * @param ref - Ref to the label element
882
 * @returns Label props
883
 */
884
function useLabel(props: LabelAriaProps, ref: RefObject<Element>): LabelAria;
885

886
interface AriaFieldProps {
887
  /** Label for the field */
888
  label?: ReactNode;
889
  /** Description for the field */
890
  description?: ReactNode;
891
  /** Error message for the field */
892
  errorMessage?: ReactNode;
893
  /** Whether the field is required */
894
  isRequired?: boolean;
895
  /** Whether the field is disabled */
896
  isDisabled?: boolean;
897
  /** Whether the field is read-only */
898
  isReadOnly?: boolean;
899
  /** Validation state */
900
  validationState?: 'valid' | 'invalid';
901
  /** Whether to include required asterisk in label */
902
  necessityIndicator?: 'icon' | 'label';
903
}
904

905
interface FieldAria {
906
  /** Props for the field wrapper */
907
  fieldProps: DOMAttributes<Element>;
908
  /** Props for the label element */
909
  labelProps: DOMAttributes<Element>;
910
  /** Props for the description element */
911
  descriptionProps: DOMAttributes<Element>;
912
  /** Props for the error message element */
913
  errorMessageProps: DOMAttributes<Element>;
914
}
915

916
interface LabelAriaProps {
917
  /** Label content */
918
  children: ReactNode;
919
  /** Target element for the label */
920
  for?: string;
921
  /** Element type to render */
922
  elementType?: React.ElementType;
923
}
924

925
interface LabelAria {
926
  /** Props for the label element */
927
  labelProps: LabelHTMLAttributes<HTMLLabelElement>;
928
}
929
```