npm-react-aria

1
# Date and Time
2

3
Date and time input components with comprehensive internationalization, accessibility, and validation support. All components handle various date formats, locales, time zones, and provide proper keyboard navigation.
4

5
## Capabilities
6

7
### Date Picker
8

9
Provides date picker behavior with calendar popup and text input.
10

11
```typescript { .api }
12
/**
13
 * Provides date picker behavior and accessibility
14
 * @param props - Date picker configuration
15
 * @param state - Date picker state management
16
 * @param ref - Ref to the date picker element
17
 * @returns Date picker props and state
18
 */
19
function useDatePicker(props: AriaDatePickerProps, state: DatePickerState, ref: RefObject<Element>): DatePickerAria;
20

21
interface AriaDatePickerProps {
22
  /** Current date value */
23
  value?: DateValue | null;
24
  /** Default date value (uncontrolled) */
25
  defaultValue?: DateValue | null;
26
  /** Handler called when date changes */
27
  onChange?: (value: DateValue | null) => void;
28
  /** Minimum allowed date */
29
  minValue?: DateValue;
30
  /** Maximum allowed date */
31
  maxValue?: DateValue;
32
  /** Whether the picker is disabled */
33
  isDisabled?: boolean;
34
  /** Whether the picker is read-only */
35
  isReadOnly?: boolean;
36
  /** Whether the picker is required */
37
  isRequired?: boolean;
38
  /** Validation state */
39
  validationState?: 'valid' | 'invalid';
40
  /** Auto-focus behavior */
41
  autoFocus?: boolean;
42
  /** Date formatting options */
43
  granularity?: 'day' | 'hour' | 'minute' | 'second';
44
  /** Hide the time zone */
45
  hideTimeZone?: boolean;
46
  /** Hour cycle preference */
47
  hourCycle?: 12 | 24;
48
  /** Whether to show era for certain calendars */
49
  showEra?: boolean;
50
  /** Placeholder date to use when value is null */
51
  placeholderValue?: DateValue;
52
  /** Whether dates are disabled */
53
  isDateUnavailable?: (date: DateValue) => boolean;
54
}
55

56
interface DatePickerAria {
57
  /** Props for the date picker group element */
58
  groupProps: DOMAttributes<Element>;
59
  /** Props for the label element */
60
  labelProps: DOMAttributes<Element>;
61
  /** Props for the date field */
62
  fieldProps: DOMAttributes<Element>;
63
  /** Props for the calendar button */
64
  buttonProps: ButtonHTMLAttributes<HTMLButtonElement>;
65
  /** Props for the dialog element */
66
  dialogProps: DOMAttributes<Element>;
67
  /** Props for the calendar element */
68
  calendarProps: DOMAttributes<Element>;
69
  /** Props for the description element */
70
  descriptionProps: DOMAttributes<Element>;
71
  /** Props for the error message element */
72
  errorMessageProps: DOMAttributes<Element>;
73
  /** Whether the calendar is open */
74
  isOpen: boolean;
75
  /** Set the calendar open state */
76
  setOpen: (isOpen: boolean) => void;
77
}
78
```
79

80
### Date Range Picker
81

82
Provides date range picker behavior for selecting start and end dates.
83

84
```typescript { .api }
85
/**
86
 * Provides date range picker behavior and accessibility
87
 * @param props - Date range picker configuration
88
 * @param state - Date range picker state
89
 * @param ref - Ref to the date range picker element
90
 * @returns Date range picker props and state
91
 */
92
function useDateRangePicker(props: AriaDateRangePickerProps, state: DateRangePickerState, ref: RefObject<Element>): DateRangePickerAria;
93

94
interface AriaDateRangePickerProps {
95
  /** Current date range value */
96
  value?: DateRange | null;
97
  /** Default date range value (uncontrolled) */
98
  defaultValue?: DateRange | null;
99
  /** Handler called when range changes */
100
  onChange?: (value: DateRange | null) => void;
101
  /** Minimum allowed date */
102
  minValue?: DateValue;
103
  /** Maximum allowed date */
104
  maxValue?: DateValue;
105
  /** Whether the picker is disabled */
106
  isDisabled?: boolean;
107
  /** Whether the picker is read-only */
108
  isReadOnly?: boolean;
109
  /** Whether the picker is required */
110
  isRequired?: boolean;
111
  /** Validation state */
112
  validationState?: 'valid' | 'invalid';
113
  /** Auto-focus behavior */
114
  autoFocus?: boolean;
115
  /** Whether dates are disabled */
116
  isDateUnavailable?: (date: DateValue) => boolean;
117
  /** Allow non-contiguous ranges */
118
  allowsNonContiguousRanges?: boolean;
119
}
120

121
interface DateRangePickerAria {
122
  /** Props for the date range picker group element */
123
  groupProps: DOMAttributes<Element>;
124
  /** Props for the label element */
125
  labelProps: DOMAttributes<Element>;
126
  /** Props for the start field */
127
  startFieldProps: DOMAttributes<Element>;
128
  /** Props for the end field */
129
  endFieldProps: DOMAttributes<Element>;
130
  /** Props for the calendar button */
131
  buttonProps: ButtonHTMLAttributes<HTMLButtonElement>;
132
  /** Props for the dialog element */
133
  dialogProps: DOMAttributes<Element>;
134
  /** Props for the range calendar element */
135
  calendarProps: DOMAttributes<Element>;
136
  /** Props for the description element */
137
  descriptionProps: DOMAttributes<Element>;
138
  /** Props for the error message element */
139
  errorMessageProps: DOMAttributes<Element>;
140
}
141
```
142

143
### Date Field
144

145
Provides date input field behavior with segment-based editing.
146

147
```typescript { .api }
148
/**
149
 * Provides date field behavior and accessibility
150
 * @param props - Date field configuration
151
 * @param state - Date field state
152
 * @param ref - Ref to the date field element
153
 * @returns Date field props and state
154
 */
155
function useDateField(props: AriaDateFieldProps, state: DateFieldState, ref: RefObject<Element>): DateFieldAria;
156

157
/**
158
 * Provides date segment behavior for individual date parts
159
 * @param segment - Date segment information
160
 * @param state - Date field state
161
 * @param ref - Ref to the segment element
162
 * @returns Date segment props and state
163
 */
164
function useDateSegment(segment: DateSegment, state: DateFieldState, ref: RefObject<Element>): DateSegmentAria;
165

166
interface AriaDateFieldProps {
167
  /** Current date value */
168
  value?: DateValue | null;
169
  /** Default date value (uncontrolled) */
170
  defaultValue?: DateValue | null;
171
  /** Handler called when date changes */
172
  onChange?: (value: DateValue | null) => void;
173
  /** Minimum allowed date */
174
  minValue?: DateValue;
175
  /** Maximum allowed date */
176
  maxValue?: DateValue;
177
  /** Whether the field is disabled */
178
  isDisabled?: boolean;
179
  /** Whether the field is read-only */
180
  isReadOnly?: boolean;
181
  /** Whether the field is required */
182
  isRequired?: boolean;
183
  /** Validation state */
184
  validationState?: 'valid' | 'invalid';
185
  /** Auto-focus behavior */
186
  autoFocus?: boolean;
187
  /** Date formatting options */
188
  granularity?: 'day' | 'hour' | 'minute' | 'second';
189
  /** Hide the time zone */
190
  hideTimeZone?: boolean;
191
  /** Hour cycle preference */
192
  hourCycle?: 12 | 24;
193
  /** Whether to show era */
194
  showEra?: boolean;
195
  /** Placeholder date to use when value is null */
196
  placeholderValue?: DateValue;
197
  /** Locale for formatting */
198
  locale?: string;
199
  /** Date formatting options */
200
  formatOptions?: Intl.DateTimeFormatOptions;
201
}
202

203
interface DateFieldAria {
204
  /** Props for the label element */
205
  labelProps: DOMAttributes<Element>;
206
  /** Props for the field group element */
207
  fieldProps: DOMAttributes<Element>;
208
  /** Props for the description element */
209
  descriptionProps: DOMAttributes<Element>;
210
  /** Props for the error message element */
211
  errorMessageProps: DOMAttributes<Element>;
212
}
213

214
interface DateSegmentAria {
215
  /** Props for the segment element */
216
  segmentProps: DOMAttributes<Element>;
217
}
218
```
219

220
### Time Field
221

222
Provides time input field behavior with hour, minute, and second segments.
223

224
```typescript { .api }
225
/**
226
 * Provides time field behavior and accessibility
227
 * @param props - Time field configuration
228
 * @param state - Time field state
229
 * @param ref - Ref to the time field element
230
 * @returns Time field props and state
231
 */
232
function useTimeField(props: AriaTimeFieldProps, state: TimeFieldState, ref: RefObject<Element>): TimeFieldAria;
233

234
interface AriaTimeFieldProps {
235
  /** Current time value */
236
  value?: TimeValue | null;
237
  /** Default time value (uncontrolled) */
238
  defaultValue?: TimeValue | null;
239
  /** Handler called when time changes */
240
  onChange?: (value: TimeValue | null) => void;
241
  /** Minimum allowed time */
242
  minValue?: TimeValue;
243
  /** Maximum allowed time */
244
  maxValue?: TimeValue;
245
  /** Whether the field is disabled */
246
  isDisabled?: boolean;
247
  /** Whether the field is read-only */
248
  isReadOnly?: boolean;
249
  /** Whether the field is required */
250
  isRequired?: boolean;
251
  /** Validation state */
252
  validationState?: 'valid' | 'invalid';
253
  /** Auto-focus behavior */
254
  autoFocus?: boolean;
255
  /** Time granularity */
256
  granularity?: 'hour' | 'minute' | 'second';
257
  /** Hide the time zone */
258
  hideTimeZone?: boolean;
259
  /** Hour cycle preference */
260
  hourCycle?: 12 | 24;
261
  /** Placeholder time to use when value is null */
262
  placeholderValue?: TimeValue;
263
}
264

265
interface TimeFieldAria {
266
  /** Props for the label element */
267
  labelProps: DOMAttributes<Element>;
268
  /** Props for the field group element */
269
  fieldProps: DOMAttributes<Element>;
270
  /** Props for the description element */
271
  descriptionProps: DOMAttributes<Element>;
272
  /** Props for the error message element */
273
  errorMessageProps: DOMAttributes<Element>;
274
}
275
```
276

277
### Calendar
278

279
Provides calendar behavior for date selection with month navigation.
280

281
```typescript { .api }
282
/**
283
 * Provides calendar behavior and accessibility
284
 * @param props - Calendar configuration
285
 * @param state - Calendar state
286
 * @param ref - Ref to the calendar element
287
 * @returns Calendar props and state
288
 */
289
function useCalendar(props: AriaCalendarProps, state: CalendarState, ref: RefObject<Element>): CalendarAria;
290

291
/**
292
 * Provides calendar grid behavior for the days grid
293
 * @param props - Calendar grid configuration
294
 * @param state - Calendar state
295
 * @param ref - Ref to the grid element
296
 * @returns Calendar grid props
297
 */
298
function useCalendarGrid(props: AriaCalendarGridProps, state: CalendarState, ref: RefObject<Element>): CalendarGridAria;
299

300
/**
301
 * Provides calendar cell behavior for individual date cells
302
 * @param props - Calendar cell configuration
303
 * @param state - Calendar state
304
 * @param ref - Ref to the cell element
305
 * @returns Calendar cell props and state
306
 */
307
function useCalendarCell(props: AriaCalendarCellProps, state: CalendarState, ref: RefObject<Element>): CalendarCellAria;
308

309
interface AriaCalendarProps extends CalendarProps {
310
  /** Current selected date(s) */
311
  value?: DateValue | DateRange | null;
312
  /** Default selected date(s) (uncontrolled) */
313
  defaultValue?: DateValue | DateRange | null;
314
  /** Handler called when selection changes */
315
  onChange?: (value: DateValue | DateRange | null) => void;
316
  /** Currently focused date */
317
  focusedValue?: DateValue;
318
  /** Default focused date (uncontrolled) */
319
  defaultFocusedValue?: DateValue;
320
  /** Handler called when focus changes */
321
  onFocusChange?: (value: DateValue) => void;
322
  /** Minimum allowed date */
323
  minValue?: DateValue;
324
  /** Maximum allowed date */
325
  maxValue?: DateValue;
326
  /** Whether the calendar is disabled */
327
  isDisabled?: boolean;
328
  /** Whether the calendar is read-only */
329
  isReadOnly?: boolean;
330
  /** Auto-focus behavior */
331
  autoFocus?: boolean;
332
  /** Whether dates are unavailable */
333
  isDateUnavailable?: (date: DateValue) => boolean;
334
  /** Validation state */
335
  validationState?: 'valid' | 'invalid';
336
  /** Error message */
337
  errorMessage?: ReactNode;
338
}
339

340
interface CalendarAria {
341
  /** Props for the calendar element */
342
  calendarProps: DOMAttributes<Element>;
343
  /** Props for the title element */
344
  titleProps: DOMAttributes<Element>;
345
  /** Props for the previous button */
346
  prevButtonProps: ButtonHTMLAttributes<HTMLButtonElement>;
347
  /** Props for the next button */
348
  nextButtonProps: ButtonHTMLAttributes<HTMLButtonElement>;
349
  /** Props for the error message element */
350
  errorMessageProps: DOMAttributes<Element>;
351
}
352
```
353

354
### Range Calendar
355

356
Provides range calendar behavior for selecting date ranges.
357

358
```typescript { .api }
359
/**
360
 * Provides range calendar behavior and accessibility
361
 * @param props - Range calendar configuration
362
 * @param state - Range calendar state
363
 * @param ref - Ref to the calendar element
364
 * @returns Range calendar props and state
365
 */
366
function useRangeCalendar(props: AriaRangeCalendarProps, state: RangeCalendarState, ref: RefObject<Element>): CalendarAria;
367

368
interface AriaRangeCalendarProps extends RangeCalendarProps {
369
  /** Current selected range */
370
  value?: DateRange | null;
371
  /** Default selected range (uncontrolled) */
372
  defaultValue?: DateRange | null;
373
  /** Handler called when range changes */
374
  onChange?: (value: DateRange | null) => void;
375
  /** Currently focused date */
376
  focusedValue?: DateValue;
377
  /** Default focused date (uncontrolled) */
378
  defaultFocusedValue?: DateValue;
379
  /** Handler called when focus changes */
380
  onFocusChange?: (value: DateValue) => void;
381
  /** Minimum allowed date */
382
  minValue?: DateValue;
383
  /** Maximum allowed date */
384
  maxValue?: DateValue;
385
  /** Whether the calendar is disabled */
386
  isDisabled?: boolean;
387
  /** Whether the calendar is read-only */
388
  isReadOnly?: boolean;
389
  /** Auto-focus behavior */
390
  autoFocus?: boolean;
391
  /** Whether dates are unavailable */
392
  isDateUnavailable?: (date: DateValue) => boolean;
393
  /** Allow non-contiguous ranges */
394
  allowsNonContiguousRanges?: boolean;
395
  /** Validation state */
396
  validationState?: 'valid' | 'invalid';
397
}
398
```
399

400
## Types
401

402
```typescript { .api }
403
interface DateValue {
404
  /** Calendar system */
405
  calendar: Calendar;
406
  /** Era */
407
  era?: string;
408
  /** Year */
409
  year: number;
410
  /** Month (1-based) */
411
  month: number;
412
  /** Day */
413
  day: number;
414
  /** Convert to native Date object */
415
  toDate(timeZone: string): Date;
416
  /** Get formatted string */
417
  toString(): string;
418
  /** Compare to another date */
419
  compare(other: DateValue): number;
420
}
421

422
interface TimeValue {
423
  /** Hour (24-hour format) */
424
  hour: number;
425
  /** Minute */
426
  minute: number;
427
  /** Second */
428
  second?: number;
429
  /** Millisecond */
430
  millisecond?: number;
431
  /** Convert to string */
432
  toString(): string;
433
  /** Compare to another time */
434
  compare(other: TimeValue): number;
435
}
436

437
interface DateRange {
438
  /** Start date */
439
  start: DateValue;
440
  /** End date */
441
  end: DateValue;
442
}
443

444
interface DateSegment {
445
  /** Type of segment */
446
  type: 'literal' | 'year' | 'month' | 'day' | 'hour' | 'minute' | 'second' | 'dayPeriod' | 'era' | 'timeZoneName';
447
  /** Display text */
448
  text: string;
449
  /** Current value */
450
  value?: number;
451
  /** Minimum value */
452
  minValue?: number;
453
  /** Maximum value */
454
  maxValue?: number;
455
  /** Whether segment is placeholder */
456
  isPlaceholder: boolean;
457
  /** Whether segment is editable */
458
  isEditable: boolean;
459
}
460

461
interface DateFieldState {
462
  /** Current date value */
463
  value: DateValue | null;
464
  /** Set the date value */
465
  setValue(value: DateValue | null): void;
466
  /** Date segments */
467
  segments: DateSegment[];
468
  /** Currently focused segment */
469
  focusedSegment: number | null;
470
  /** Set the focused segment */
471
  setFocusedSegment(index: number | null): void;
472
  /** Increment a segment */
473
  increment(index: number): void;
474
  /** Decrement a segment */
475
  decrement(index: number): void;
476
  /** Set segment value */
477
  setSegment(index: number, value: number): void;
478
  /** Clear the value */
479
  clearSegment(index: number): void;
480
  /** Whether the field is invalid */
481
  isInvalid: boolean;
482
  /** Validation state */
483
  validationState: 'valid' | 'invalid';
484
}
485

486
interface CalendarState {
487
  /** Current date value */
488
  value: DateValue | DateRange | null;
489
  /** Set the date value */
490
  setValue(value: DateValue | DateRange | null): void;
491
  /** Currently focused date */
492
  focusedDate: DateValue;
493
  /** Set the focused date */
494
  setFocusedDate(date: DateValue): void;
495
  /** Navigate to previous month */
496
  focusPreviousPage(): void;
497
  /** Navigate to next month */
498
  focusNextPage(): void;
499
  /** Navigate to previous year */
500
  focusPreviousYear(): void;
501
  /** Navigate to next year */
502
  focusNextYear(): void;
503
  /** Select a date */
504
  selectDate(date: DateValue): void;
505
  /** Whether a date is selected */
506
  isSelected(date: DateValue): boolean;
507
  /** Whether a date is focused */
508
  isFocused(date: DateValue): boolean;
509
  /** Whether a date is disabled */
510
  isDisabled(date: DateValue): boolean;
511
  /** Whether a date is unavailable */
512
  isUnavailable(date: DateValue): boolean;
513
}
514
```