useDatePicker

Provides the behavior and accessibility implementation for a date picker component. A date picker combines a DateField and a Calendar popover to allow users to enter or select a date and time value.

Event date

mmddyyyy

Example

DatePicker.tsx

DatePicker.css

DateField.css

Calendar.css

Button.css

Form.css

Popover.css

Example

DatePicker.tsx

DatePicker.css

DateField.css

Calendar.css

Button.css

Form.css

Popover.css

import {DatePicker} from './DatePicker';

<DatePicker label="Event date" />

API

<DatePicker>
  <Label />
  <Group>
    <DateInput>
      {segment => <DateSegment segment={segment} />}
    </DateInput>
    <Button />
  </Group>
  <Popover>
    <Calendar />
  </Popover>
</DatePicker>

useDatePickerState<T extends DateValue = DateValue>(props: DatePickerStateOptions<T>): DatePickerState

useDatePicker<T extends DateValue>(
  props: AriaDatePickerProps<T>,
state: DatePickerState,
ref: RefObject<Element | null>
): DatePickerAria

DatePickerState

Properties

Name	Type
`dateValue`	`DateValue \| null`
The date portion of the value. This may be set prior to `value` if the user has selected a date but has not yet selected a time.
`timeValue`	`TimeValue \| null`
The time portion of the value. This may be set prior to `value` if the user has selected a time but has not yet selected a date.
`granularity`	`Granularity`
The granularity for the field, based on the `granularity` prop and current value.
`hasTime`	`boolean`
Whether the date picker supports selecting a time, according to the `granularity` prop and current value.
`point`	`Point \| null`
The cursor position when the overlay was triggered, relative to the window viewport.
`realtimeValidation`	`ValidationResult`
Realtime validation results, updated as the user edits the value.
`displayValidation`	`ValidationResult`
Currently displayed validation results, updated when the user commits their changes.

`value`	`DateValue \| null`
The currently selected date.
`defaultValue`	`DateValue \| null`
The default date.

Methods

`setValue(value: DateValue \| null): void`
Sets the selected date.
`setDateValue(value: DateValue): void`
Sets the date portion of the value.
`setTimeValue(value: TimeValue): void`
Sets the time portion of the value.
`setOpen(isOpen: boolean): void`
Sets whether the calendar popover is open.
`formatValue(locale: string, fieldOptions: FieldOptions): string`
Formats the selected value using the given options.
`getDateFormatter(locale: string, formatOptions: FormatterOptions): DateFormatter`
Gets a formatter based on state's props.
`open(): void`
Opens the overlay.
`close(): void`
Closes the overlay.
`toggle(): void`
Toggles the overlay's visibility.
`setPoint(point: Point): void`
Sets the cursor position relative to the window viewport.
`updateValidation(result: ValidationResult): void`
Updates the current validation result. Not displayed to the user until `commitValidation` is called.
`resetValidation(): void`
Resets the displayed validation state to valid when the user resets the form.
`commitValidation(): void`
Commits the realtime validation so it is displayed to the user.

AriaDatePickerProps

Name	Type	Default
`pageBehavior`	`PageBehavior`	Default: `visible`
Controls the behavior of paging. Pagination either works by advancing the visible page by visibleDuration (default) or one unit of visibleDuration.
`firstDayOfWeek`	`'sun' \| 'mon' \| 'tue' \| 'wed' \| 'thu' \| 'fri' \| 'sat'`	Default: —
The day that starts the week.
`isDateUnavailable`	`(date: DateValue) => boolean`	Default: —
Callback that is called for each date of the calendar. If it returns true, then the date is unavailable.
`placeholderValue`	`DateValue \| null`	Default: —
A placeholder date that influences the format of the placeholder shown when no value is selected. Defaults to today's date at midnight.
`hourCycle`	`12 \| 24`	Default: —
Whether to display the time in 12 or 24 hour format. By default, this is determined by the user's locale.
`granularity`	`Granularity`	Default: —
Determines the smallest unit that is displayed in the date picker. By default, this is `"day"` for dates, and `"minute"` for times.
`hideTimeZone`	`boolean`	Default: `false`
Whether to hide the time zone abbreviation.
`shouldForceLeadingZeros`	`boolean`	Default: —
Whether to always show leading zeros in the month, day, and hour fields. By default, this is determined by the user's locale.
`isDisabled`	`boolean`	Default: —
Whether the input is disabled.
`isReadOnly`	`boolean`	Default: —
Whether the input can be selected but not changed by the user.

`value`	`DateValue \| null`	Default: —
The current value (controlled).
`defaultValue`	`DateValue \| null`	Default: —
The default value (uncontrolled).
`onChange`	`(value: MappedDateValue<DateValue> \| null) => void`	Default: —
Handler that is called when the value changes.

DatePickerAria

Name	Type
`labelProps`	`DOMAttributes`
Props for the date picker's visible label element, if any.
`groupProps`
Props for the grouping element containing the date field and button.
`fieldProps`	`<DateValue>`
Props for the date field.
`buttonProps`	`AriaButtonProps`
Props for the popover trigger button.
`descriptionProps`	`DOMAttributes`
Props for the description element, if any.
`errorMessageProps`	`DOMAttributes`
Props for the error message element, if any.
`dialogProps`	`AriaDialogProps`
Props for the popover dialog.
`calendarProps`	`CalendarProps<DateValue>`
Props for the calendar within the popover dialog.
`validationDetails`	`ValidityState`
The native validation details for the input.