npm-react-aria

1
# Form Controls
2

3
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.
4

5
## Capabilities
6

7
### Button
8

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

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

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

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

53
**Usage Example:**
54

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

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

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

74
### Toggle Button
75

76
Provides toggle button behavior with pressed state management.
77

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

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

95
### Toggle Button Group
96

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

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

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

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

133
### Text Field
134

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

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

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

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

189
### Checkbox
190

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

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

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

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

245
### Checkbox Group
246

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

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

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

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

293
### Radio Button
294

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

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

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

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

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

353
### Switch
354

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

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

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

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

401
### Number Field
402

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

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

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

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

455
### Search Field
456

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

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

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

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

481
### Color Components
482

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

700
### Progress and Measurement
701

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

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

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

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

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

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

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

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

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

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

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

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

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

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

866
### Labeling and Fields
867

868
Utilities for form field labeling and accessibility.
869

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

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

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

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

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

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