useDatePickerState

Provides state management 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.

install	`yarn add react-stately`
version	3.33.0
usage	`import {useDatePickerState} from 'react-stately'`

View repository

GitHub

View package

NPM

API#

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

Interface#

Properties

Name	Type	Description
`value`	`DateValue \| null`	The currently selected date.
`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.
`isOpen`	`boolean`	Whether the calendar popover is currently open.
`isInvalid`	`boolean`	Whether the date picker is invalid, based on the `isInvalid`, `minValue`, and `maxValue` props.
`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.

Methods

Method	Description
`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.
`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.

Example#

See the docs for useDatePicker in react-aria for an example of useDatePickerState.

CalendarDate
  | CalendarDateTime
  | ZonedDateTime

A CalendarDate represents a date without any time components in a specific calendar system.

Properties

Name	Type	Description
`calendar`	`Calendar`	The calendar system associated with this date, e.g. Gregorian.
`era`	`string`	The calendar era for this date, e.g. "BC" or "AD".
`year`	`number`	The year of this date within the era.
`month`	`number`	The month number within the year. Note that some calendar systems such as Hebrew may have a variable number of months per year. Therefore, month numbers may not always correspond to the same month names in different years.
`day`	`number`	The day number within the month.

Methods

Method	Description
`constructor( (...args: any[] )): void`
`copy(): CalendarDate`	Returns a copy of this date.
`add( (duration: DateDuration )): CalendarDate`	Returns a new `CalendarDate` with the given duration added to it.
`subtract( (duration: DateDuration )): CalendarDate`	Returns a new `CalendarDate` with the given duration subtracted from it.
`set( (fields: DateFields )): CalendarDate`	Returns a new `CalendarDate` with the given fields set to the provided values. Other fields will be constrained accordingly.
`cycle( field: DateField, amount: number, options?: CycleOptions ): CalendarDate`	Returns a new `CalendarDate` with the given field adjusted by a specified amount. When the resulting value reaches the limits of the field, it wraps around.
`toDate( (timeZone: string )): Date`	Converts the date to a native JavaScript Date object, with the time set to midnight in the given time zone.
`toString(): string`	Converts the date to an ISO 8601 formatted string.
`compare( (b: AnyCalendarDate )): number`	Compares this date with another. A negative result indicates that this date is before the given one, and a positive date indicates that it is after.

A CalendarDateTime represents a date and time without a time zone, in a specific calendar system.

Properties

Name	Type	Description
`calendar`	`Calendar`	The calendar system associated with this date, e.g. Gregorian.
`era`	`string`	The calendar era for this date, e.g. "BC" or "AD".
`year`	`number`	The year of this date within the era.
`month`	`number`	The month number within the year. Note that some calendar systems such as Hebrew may have a variable number of months per year. Therefore, month numbers may not always correspond to the same month names in different years.
`day`	`number`	The day number within the month.
`hour`	`number`	The hour in the day, numbered from 0 to 23.
`minute`	`number`	The minute in the hour.
`second`	`number`	The second in the minute.
`millisecond`	`number`	The millisecond in the second.

Methods

Method	Description
`constructor( (...args: any[] )): void`
`copy(): CalendarDateTime`	Returns a copy of this date.
`add( (duration: DateTimeDuration )): CalendarDateTime`	Returns a new `CalendarDateTime` with the given duration added to it.
`subtract( (duration: DateTimeDuration )): CalendarDateTime`	Returns a new `CalendarDateTime` with the given duration subtracted from it.
`set( (fields: DateFields & & TimeFields )): CalendarDateTime`	Returns a new `CalendarDateTime` with the given fields set to the provided values. Other fields will be constrained accordingly.
`cycle( field: DateField \| \| TimeField, amount: number, options?: CycleTimeOptions ): CalendarDateTime`	Returns a new `CalendarDateTime` with the given field adjusted by a specified amount. When the resulting value reaches the limits of the field, it wraps around.
`toDate( (timeZone: string, , disambiguation?: Disambiguation )): Date`	Converts the date to a native JavaScript Date object in the given time zone.
`toString(): string`	Converts the date to an ISO 8601 formatted string.
`compare( (b: CalendarDate \| CalendarDateTime \| ZonedDateTime )): number`	Compares this date with another. A negative result indicates that this date is before the given one, and a positive date indicates that it is after.

A ZonedDateTime represents a date and time in a specific time zone and calendar system.

Properties

Name	Type	Description
`calendar`	`Calendar`	The calendar system associated with this date, e.g. Gregorian.
`era`	`string`	The calendar era for this date, e.g. "BC" or "AD".
`year`	`number`	The year of this date within the era.
`month`	`number`	The month number within the year. Note that some calendar systems such as Hebrew may have a variable number of months per year. Therefore, month numbers may not always correspond to the same month names in different years.
`day`	`number`	The day number within the month.
`hour`	`number`	The hour in the day, numbered from 0 to 23.
`minute`	`number`	The minute in the hour.
`second`	`number`	The second in the minute.
`millisecond`	`number`	The millisecond in the second.
`timeZone`	`string`	The IANA time zone identifier that this date and time is represented in.
`offset`	`number`	The UTC offset for this time, in milliseconds.

Methods

Method	Description
`constructor( (...args: any[] )): void`
`copy(): ZonedDateTime`	Returns a copy of this date.
`add( (duration: DateTimeDuration )): void`	Returns a new `ZonedDateTime` with the given duration added to it.
`subtract( (duration: DateTimeDuration )): void`	Returns a new `ZonedDateTime` with the given duration subtracted from it.
`set( (fields: DateFields & & TimeFields, , disambiguation?: Disambiguation )): void`	Returns a new `ZonedDateTime` with the given fields set to the provided values. Other fields will be constrained accordingly.
`cycle( field: DateField \| \| TimeField, amount: number, options?: CycleTimeOptions ): void`	Returns a new `ZonedDateTime` with the given field adjusted by a specified amount. When the resulting value reaches the limits of the field, it wraps around.
`toDate(): void`	Converts the date to a native JavaScript Date object.
`toString(): void`	Converts the date to an ISO 8601 formatted string, including the UTC offset and time zone identifier.
`toAbsoluteString(): void`	Converts the date to an ISO 8601 formatted string in UTC.
`compare( (b: CalendarDate \| CalendarDateTime \| ZonedDateTime )): void`	Compares this date with another. A negative result indicates that this date is before the given one, and a positive date indicates that it is after.

Name	Type	Default	Description
`shouldCloseOnSelect`	`boolean \| () => boolean`	`true`	Determines whether the date picker popover should close automatically when a date is selected.
`pageBehavior`	`PageBehavior`	`visible`	Controls the behavior of paging. Pagination either works by advancing the visible page by visibleDuration (default) or one unit of visibleDuration.
`minValue`	`DateValue \| null`	—	The minimum allowed date that a user may select.
`maxValue`	`DateValue \| null`	—	The maximum allowed date that a user may select.
`isDateUnavailable`	`( (date: DateValue )) => boolean`	—	Callback that is called for each date of the calendar. If it returns true, then the date is unavailable.
`placeholderValue`	`DateValue \| null`	—	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`	—	Whether to display the time in 12 or 24 hour format. By default, this is determined by the user's locale.
`granularity`	`Granularity`	—	Determines the smallest unit that is displayed in the date picker. By default, this is `"day"` for dates, and `"minute"` for times.
`hideTimeZone`	`boolean`	`false`	Whether to hide the time zone abbreviation.
`shouldForceLeadingZeros`	`boolean`	—	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`	—	Whether the input is disabled.
`isReadOnly`	`boolean`	—	Whether the input can be selected but not changed by the user.
`isRequired`	`boolean`	—	Whether user input is required on the input before form submission.
`isInvalid`	`boolean`	—	Whether the input value is invalid.
`validationBehavior`	`'aria' \| 'native'`	`'aria'`	Whether to use native HTML form validation to prevent form submission when the value is missing or invalid, or mark the field as required or invalid via ARIA.
`validate`	`( (value: MappedDateValue<DateValue> )) => ValidationError \| true \| null \| undefined`	—	A function that returns an error message if a given value is invalid. Validation errors are displayed to the user when the form is submitted if `validationBehavior="native"`. For realtime validation, use the `isInvalid` prop instead.
`autoFocus`	`boolean`	—	Whether the element should receive focus on render.
`onFocus`	`( (e: FocusEvent<Target> )) => void`	—	Handler that is called when the element receives focus.
`onBlur`	`( (e: FocusEvent<Target> )) => void`	—	Handler that is called when the element loses focus.
`onFocusChange`	`( (isFocused: boolean )) => void`	—	Handler that is called when the element's focus status changes.
`onKeyDown`	`( (e: KeyboardEvent )) => void`	—	Handler that is called when a key is pressed.
`onKeyUp`	`( (e: KeyboardEvent )) => void`	—	Handler that is called when a key is released.
`label`	`ReactNode`	—	The content to display as the label.
`description`	`ReactNode`	—	A description for the field. Provides a hint such as specific requirements for what to choose.
`errorMessage`	`ReactNode \| ( (v: ValidationResult )) => ReactNode`	—	An error message for the field.
`isOpen`	`boolean`	—	Whether the overlay is open by default (controlled).
`defaultOpen`	`boolean`	—	Whether the overlay is open by default (uncontrolled).
`onOpenChange`	`( (isOpen: boolean )) => void`	—	Handler that is called when the overlay's open state changes.
`value`	`DateValue \| null`	—	The current value (controlled).
`defaultValue`	`DateValue \| null`	—	The default value (uncontrolled).
`onChange`	`( (value: MappedDateValue<DateValue> \| \| null )) => void`	—	Handler that is called when the value changes.

'single' | 'visible'

'day'
  | 'hour'
  | 'minute'
  | 'second'

'valid' | 'invalid'

DateValue extends ZonedDateTime ? ZonedDateTime :
DateValue extends CalendarDateTime ? CalendarDateTime :
DateValue extends CalendarDate ? CalendarDate : never

string | string[]

BaseEvent<ReactKeyboardEvent<any>>

SyntheticEvent & {stopPropagation: () => void,
continuePropagation: () => void
}

Name	Type	Description
`isInvalid`	`boolean`	Whether the input value is invalid.
`validationErrors`	`string[]`	The current error messages for the input if it is invalid, otherwise an empty array.
`validationDetails`	`ValidityState`	The native validation details for the input.

Properties

Name	Type	Description
`value`	`DateValue \| null`	The currently selected date.
`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.
`isOpen`	`boolean`	Whether the calendar popover is currently open.
`isInvalid`	`boolean`	Whether the date picker is invalid, based on the `isInvalid`, `minValue`, and `maxValue` props.
`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.

Methods

Method	Description
`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.
`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.

Time
  | CalendarDateTime
  | ZonedDateTime

A Time represents a clock time without any date components.

Properties

Name	Type	Description
`hour`	`number`	The hour, numbered from 0 to 23.
`minute`	`number`	The minute in the hour.
`second`	`number`	The second in the minute.
`millisecond`	`number`	The millisecond in the second.

Methods

Method	Description
`constructor( hour: number, minute: number, second: number, millisecond: number ): void`
`copy(): Time`	Returns a copy of this time.
`add( (duration: TimeDuration )): void`	Returns a new `Time` with the given duration added to it.
`subtract( (duration: TimeDuration )): void`	Returns a new `Time` with the given duration subtracted from it.
`set( (fields: TimeFields )): void`	Returns a new `Time` with the given fields set to the provided values. Other fields will be constrained accordingly.
`cycle( field: TimeField, amount: number, options?: CycleTimeOptions ): void`	Returns a new `Time` with the given field adjusted by a specified amount. When the resulting value reaches the limits of the field, it wraps around.
`toString(): void`	Converts the time to an ISO 8601 formatted string.
`compare( (b: AnyTime )): void`	Compares this time with another. A negative result indicates that this time is before the given one, and a positive time indicates that it is after.

Intl.DateTimeFormatOptions<Intl.DateTimeFormatOptions, 'year'
  | 'month'
  | 'day'
  | 'hour'
  | 'minute'
  | 'second'>

Name	Type	Description
`timeZone`	`string`
`hideTimeZone`	`boolean`
`granularity`	`DatePickerProps<any>['granularity']`
`maxGranularity`	`'year' \| 'month' \| DatePickerProps<any>['granularity']`
`hourCycle`	`12 \| 24`
`showEra`	`boolean`
`shouldForceLeadingZeros`	`boolean`

Name	Type	Default	Description
`pageBehavior`	`PageBehavior`	`visible`	Controls the behavior of paging. Pagination either works by advancing the visible page by visibleDuration (default) or one unit of visibleDuration.
`minValue`	`DateValue \| null`	—	The minimum allowed date that a user may select.
`maxValue`	`DateValue \| null`	—	The maximum allowed date that a user may select.
`isDateUnavailable`	`( (date: DateValue )) => boolean`	—	Callback that is called for each date of the calendar. If it returns true, then the date is unavailable.
`placeholderValue`	`DateValue \| null`	—	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`	—	Whether to display the time in 12 or 24 hour format. By default, this is determined by the user's locale.
`granularity`	`Granularity`	—	Determines the smallest unit that is displayed in the date picker. By default, this is `"day"` for dates, and `"minute"` for times.
`hideTimeZone`	`boolean`	`false`	Whether to hide the time zone abbreviation.
`shouldForceLeadingZeros`	`boolean`	—	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`	—	Whether the input is disabled.
`isReadOnly`	`boolean`	—	Whether the input can be selected but not changed by the user.
`isRequired`	`boolean`	—	Whether user input is required on the input before form submission.
`isInvalid`	`boolean`	—	Whether the input value is invalid.
`validationBehavior`	`'aria' \| 'native'`	`'aria'`	Whether to use native HTML form validation to prevent form submission when the value is missing or invalid, or mark the field as required or invalid via ARIA.
`validate`	`( (value: MappedDateValue<DateValue> )) => ValidationError \| true \| null \| undefined`	—	A function that returns an error message if a given value is invalid. Validation errors are displayed to the user when the form is submitted if `validationBehavior="native"`. For realtime validation, use the `isInvalid` prop instead.
`autoFocus`	`boolean`	—	Whether the element should receive focus on render.
`onFocus`	`( (e: FocusEvent<Target> )) => void`	—	Handler that is called when the element receives focus.
`onBlur`	`( (e: FocusEvent<Target> )) => void`	—	Handler that is called when the element loses focus.
`onFocusChange`	`( (isFocused: boolean )) => void`	—	Handler that is called when the element's focus status changes.
`onKeyDown`	`( (e: KeyboardEvent )) => void`	—	Handler that is called when a key is pressed.
`onKeyUp`	`( (e: KeyboardEvent )) => void`	—	Handler that is called when a key is released.
`label`	`ReactNode`	—	The content to display as the label.
`description`	`ReactNode`	—	A description for the field. Provides a hint such as specific requirements for what to choose.
`errorMessage`	`ReactNode \| ( (v: ValidationResult )) => ReactNode`	—	An error message for the field.
`isOpen`	`boolean`	—	Whether the overlay is open by default (controlled).
`defaultOpen`	`boolean`	—	Whether the overlay is open by default (uncontrolled).
`onOpenChange`	`( (isOpen: boolean )) => void`	—	Handler that is called when the overlay's open state changes.
`value`	`DateValue \| null`	—	The current value (controlled).
`defaultValue`	`DateValue \| null`	—	The default value (uncontrolled).
`onChange`	`( (value: MappedDateValue<DateValue> \| \| null )) => void`	—	Handler that is called when the value changes.

A wrapper around Intl.DateTimeFormat that fixes various browser bugs, and polyfills new features.

Method	Description
`constructor( (locale: string, , options: Intl.DateTimeFormatOptions )): void`
`format( (value: Date )): string`	Formats a date as a string according to the locale and format options passed to the constructor.
`formatToParts( (value: Date )): Intl.DateTimeFormatPart[]`	Formats a date to an array of parts such as separators, numbers, punctuation, and more.
`formatRange( (start: Date, , end: Date )): string`	Formats a date range as a string.
`formatRangeToParts( (start: Date, , end: Date )): DateRangeFormatPart[]`	Formats a date range as an array of parts.
`resolvedOptions(): Intl.ResolvedDateTimeFormatOptions`	Returns the resolved formatting options based on the values passed to the constructor.

Name	Type	Description
`source`	`'startRange' \| 'endRange' \| 'shared'`