useDateField

Provides the behavior and accessibility implementation for a date field component. A date field allows users to enter and edit date and time values using a keyboard. Each part of a date value is displayed in an individually editable segment.

Event date

mmddyyyy

Example

DateField.tsx

DateField.css

Form.css

Example

DateField.tsx

DateField.css

Form.css

import {DateField} from './DateField';

<DateField label="Event date" />

API

<DateField>
  <Label />
  <DateInput>
    {segment => <DateSegment segment={segment} />}
  </DateInput>
  <Text slot="description" />
  <FieldError />
</DateField>

useDateFieldState<T extends DateValue = DateValue>(props: DateFieldStateOptions<T>): DateFieldState

useDateField<T extends DateValue>(
  props: AriaDateFieldOptions<T>,
state: DateFieldState,
ref: RefObject<Element | null>
): DateFieldAria

useDateSegment(
  segment: DateSegment,
state: DateFieldState,
ref: RefObject<HTMLElement | null>
): DateSegmentAria

DateFieldState

Properties

Name	Type
`dateValue`	`Date`
The current value, converted to a native JavaScript `Date` object.
`calendar`	`Calendar`
The calendar system currently in use.
`segments`	`DateSegment[]`
A list of segments for the current value.
`dateFormatter`	`DateFormatter`
A date formatter configured for the current locale and format.
`granularity`	`Granularity`
The granularity for the field, based on the `granularity` prop and current value.
`maxGranularity`	`'year' \| 'month' \| Granularity`
The maximum date or time unit that is displayed in the field.
`isDisabled`	`boolean`
Whether the field is disabled.
`isReadOnly`	`boolean`
Whether the field is read only.
`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 current field value.
`defaultValue`	`DateValue \| null`
The default field value.

Methods

`setValue(value: DateValue \| null): void`
Sets the field's value.
`increment(type: DateSegmentType): void`
Increments the given segment. Upon reaching the minimum or maximum value, the value wraps around to the opposite limit.
`decrement(type: DateSegmentType): void`
Decrements the given segment. Upon reaching the minimum or maximum value, the value wraps around to the opposite limit.
`incrementPage(type: DateSegmentType): void`
Increments the given segment by a larger amount, rounding it to the nearest increment. The amount to increment by depends on the field, for example 15 minutes, 7 days, and 5 years. Upon reaching the minimum or maximum value, the value wraps around to the opposite limit.
`decrementPage(type: DateSegmentType): void`
Decrements the given segment by a larger amount, rounding it to the nearest increment. The amount to decrement by depends on the field, for example 15 minutes, 7 days, and 5 years. Upon reaching the minimum or maximum value, the value wraps around to the opposite limit.
`incrementToMax(type: DateSegmentType): void`
Increments the given segment to its maxiumum value.
`decrementToMin(type: DateSegmentType): void`
Decrements the given segment to its minimum value.
`setSegment(type: DateSegmentType, value: number): void`
Sets the value of the given segment.
`confirmPlaceholder(): void`
Updates the remaining unfilled segments with the placeholder value.
`clearSegment(type: DateSegmentType): void`
Clears the value of the given segment, reverting it to the placeholder.
`formatValue(fieldOptions: FieldOptions): string`
Formats the current date value using the given options.
`getDateFormatter(locale: string, formatOptions: FormatterOptions): DateFormatter`
Gets a formatter based on state's props.
`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.

AriaDateFieldProps

Name	Type	Default
`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.

DateFieldAria

Name	Type
`labelProps`	`DOMAttributes`
Props for the field's visible label element, if any.
`fieldProps`	`GroupDOMAttributes`
Props for the field grouping element.
`inputProps`	`InputHTMLAttributes<HTMLInputElement>`
Props for the hidden input element for HTML form submission.
`descriptionProps`	`DOMAttributes`
Props for the description element, if any.
`errorMessageProps`	`DOMAttributes`
Props for the error message element, if any.
`validationDetails`	`ValidityState`
The native validation details for the input.