useTimeFieldState

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

install	`yarn add @react-stately/datepicker`
version	3.0.0-rc.0
usage	`import {useTimeFieldState} from '@react-stately/datepicker'`

View repository

GitHub

View package

NPM

API#

useTimeFieldState(
  (props: TimeFieldStateOptions
)): DateFieldState

Interface#

Properties

Name	Type	Description
`value`	`DateValue`	The current field value.
`dateValue`	`Date`	The current value, converted to a native JavaScript `Date` object.
`segments`	`DateSegment[]`	A list of segments for the current value.
`dateFormatter`	`DateFormatter`	A date formatter configured for the current locale and format.
`validationState`	`ValidationState`	The current validation state of the date field, based on the `validationState`, `minValue`, and `maxValue` props.
`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.
`isRequired`	`boolean`	Whether the field is required.

Methods

Method	Description
`setValue( (value: DateValue )): void`	Sets the field's value.
`increment( (type: SegmentType )): void`	Increments the given segment. Upon reaching the minimum or maximum value, the value wraps around to the opposite limit.
`decrement( (type: SegmentType )): void`	Decrements the given segment. Upon reaching the minimum or maximum value, the value wraps around to the opposite limit.
`incrementPage( (type: SegmentType )): 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: SegmentType )): 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.
`setSegment( (type: SegmentType, , value: number )): void`	Sets the value of the given segment.
`confirmPlaceholder( (type?: SegmentType )): void`	Replaces the value of the date field with the placeholder value. If a segment type is provided, only that segment is confirmed. Otherwise, all segments that have not been entered yet are confirmed.
`clearSegment( (type: SegmentType )): 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.

Example#

See the docs for useTimeField in react-aria for an example of useTimeFieldState.

Name	Type	Default	Description
`locale`	`string`	—	The locale to display and edit the value according to.
`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`	`'hour' \| 'minute' \| 'second' \| 'millisecond'`	`'minute'`	Determines the smallest unit that is displayed in the time picker.
`hideTimeZone`	`boolean`	—	Whether to hide the time zone abbreviation.
`placeholderValue`	`TimeValue`	—	A placeholder time to display when no value is selected. Defaults to 12:00 or 00:00 depending on the hour cycle.
`minValue`	`TimeValue`	—	The minimum allowed time that a user may select.
`maxValue`	`TimeValue`	—	The maximum allowed time that a user may select.
`isDisabled`	`boolean`	—	Whether the input is disabled.
`isReadOnly`	`boolean`	—	Whether the input can be selected but not changed by the user.
`validationState`	`ValidationState`	—	Whether the input should display its "valid" or "invalid" visual styling.
`isRequired`	`boolean`	—	Whether user input is required on the input before form submission. Often paired with the `necessityIndicator` prop to add a visual indicator to the input.
`autoFocus`	`boolean`	—	Whether the element should receive focus on render.
`onFocus`	`( (e: FocusEvent )) => void`	—	Handler that is called when the element receives focus.
`onBlur`	`( (e: FocusEvent )) => 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`	—	An error message for the field.
`value`	`TimeValue`	—	The current value (controlled).
`defaultValue`	`TimeValue`	—	The default value (uncontrolled).
`onChange`	`( (value: MappedTimeValue<TimeValue> )) => void`	—	Handler that is called when the value changes.

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.

Represents an amount of time, for use whe performing arithmetic.

Name	Type	Description
`hours`	`number`	The number of hours to add or subtract.
`minutes`	`number`	The number of minutes to add or subtract.
`seconds`	`number`	The number of seconds to add or subtract.
`milliseconds`	`number`	The number of milliseconds to add or subtract.

Name	Type	Description
`hour`	`number`
`minute`	`number`
`second`	`number`
`millisecond`	`number`

'hour'
  | 'minute'
  | 'second'
  | 'millisecond'

Name	Type	Default	Description
`hourCycle`	`12 \| 24`	`24`	Whether to use 12 or 24 hour time. If 12 hour time is chosen, the resulting value will remain in the same day period as the original value (e.g. if the value is AM, the resulting value also be AM).
`round`	`boolean`	—	Whether to round the field value to the nearest interval of the amount.

Name	Type	Description
`hour`	`number`
`minute`	`number`
`second`	`number`
`millisecond`	`number`

Method	Description
`copy():`

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.

The Calendar interface represents a calendar system, including information about how days, months, years, and eras are organized, and methods to perform arithmetic on dates.

Properties

Name	Type	Description
`identifier`	`string`	A string identifier for the calendar, as defined by Unicode CLDR.

Methods

Method	Description
`fromJulianDay( (jd: number )): CalendarDate`	Creates a CalendarDate in this calendar from the given Julian day number.
`toJulianDay( (date: AnyCalendarDate )): number`	Converts a date in this calendar to a Julian day number.
`getDaysInMonth( (date: AnyCalendarDate )): number`	Returns the number of days in the month of the given date.
`getMonthsInYear( (date: AnyCalendarDate )): number`	Returns the number of months in the year of the given date.
`getYearsInEra( (date: AnyCalendarDate )): number`	Returns the number of years in the era of the given date.
`getEras(): string[]`	Returns a list of era identifiers for the calendar.
`getMinimumMonthInYear( (date: AnyCalendarDate )): number`	Returns the minimum month number of the given date's year. Normally, this is 1, but in some calendars such as the Japanese, eras may begin in the middle of a year.
`getMinimumDayInMonth( (date: AnyCalendarDate )): number`	Returns the minimum day number of the given date's month. Normally, this is 1, but in some calendars such as the Japanese, eras may begin in the middle of a month.

Name	Type	Description
`calendar`	`Calendar`
`era`	`string`
`year`	`number`
`month`	`number`
`day`	`number`

Method	Description
`copy():`

Represents an amount of time with both date and time components, for use when performing arithmetic.

Name	Type	Description
`years`	`number`	The number of years to add or subtract.
`months`	`number`	The number of months to add or subtract.
`weeks`	`number`	The number of weeks to add or subtract.
`days`	`number`	The number of days to add or subtract.
`hours`	`number`	The number of hours to add or subtract.
`minutes`	`number`	The number of minutes to add or subtract.
`seconds`	`number`	The number of seconds to add or subtract.
`milliseconds`	`number`	The number of milliseconds to add or subtract.

Name	Type	Description
`era`	`string`
`year`	`number`
`month`	`number`
`day`	`number`

'era'
  | 'year'
  | 'month'
  | 'day'

'compatible'
  | 'earlier'
  | 'later'
  | 'reject'

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.

Represents an amount of time in calendar-specific units, for use when performing arithmetic.

Name	Type	Description
`years`	`number`	The number of years to add or subtract.
`months`	`number`	The number of months to add or subtract.
`weeks`	`number`	The number of weeks to add or subtract.
`days`	`number`	The number of days to add or subtract.

Name	Type	Description
`round`	`boolean`	Whether to round the field value to the nearest interval of the amount.

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 seconds.

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.

'valid' | 'invalid'

BaseEvent<ReactKeyboardEvent<any>>

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

TimeValue extends ZonedDateTime ? ZonedDateTime :
TimeValue extends CalendarDateTime ? CalendarDateTime :
TimeValue extends Time ? Time : never

Properties

Name	Type	Description
`value`	`DateValue`	The current field value.
`dateValue`	`Date`	The current value, converted to a native JavaScript `Date` object.
`segments`	`DateSegment[]`	A list of segments for the current value.
`dateFormatter`	`DateFormatter`	A date formatter configured for the current locale and format.
`validationState`	`ValidationState`	The current validation state of the date field, based on the `validationState`, `minValue`, and `maxValue` props.
`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.
`isRequired`	`boolean`	Whether the field is required.

Methods

Method	Description
`setValue( (value: DateValue )): void`	Sets the field's value.
`increment( (type: SegmentType )): void`	Increments the given segment. Upon reaching the minimum or maximum value, the value wraps around to the opposite limit.
`decrement( (type: SegmentType )): void`	Decrements the given segment. Upon reaching the minimum or maximum value, the value wraps around to the opposite limit.
`incrementPage( (type: SegmentType )): 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: SegmentType )): 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.
`setSegment( (type: SegmentType, , value: number )): void`	Sets the value of the given segment.
`confirmPlaceholder( (type?: SegmentType )): void`	Replaces the value of the date field with the placeholder value. If a segment type is provided, only that segment is confirmed. Otherwise, all segments that have not been entered yet are confirmed.
`clearSegment( (type: SegmentType )): 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.

CalendarDate
  | CalendarDateTime
  | ZonedDateTime

Name	Type	Description
`type`	`SegmentType`	The type of segment.
`text`	`string`	The formatted text for the segment.
`isPlaceholder`	`boolean`	Whether the value is a placeholder.
`isEditable`	`boolean`	Whether the segment is editable.
`value`	`number`	The numeric value for the segment, if applicable.
`minValue`	`number`	The minimum numeric value for the segment, if applicable.
`maxValue`	`number`	The maximum numeric value for the segment, if applicable.

'era'
  | 'year'
  | 'month'
  | 'day'
  | 'hour'
  | 'minute'
  | 'second'
  | 'dayPeriod'
  | 'literal'
  | 'timeZoneName'

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(): ResolvedDateTimeFormatOptions`	Returns the resolved formatting options based on the values passed to the constructor.

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

Name	Type	Description
`hourCycle`

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

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