0
# Date and Time
1

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

4
## Capabilities
5

6
### Date Picker
7

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

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

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

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

79
### Date Range Picker
80

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

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

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

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

142
### Date Field
143

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

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

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

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

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

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

219
### Time Field
220

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

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

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

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

276
### Calendar
277

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

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

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

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

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

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

353
### Range Calendar
354

355
Provides range calendar behavior for selecting date ranges.
356

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

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

399
## Types
400

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

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

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

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

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

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