useDateFieldState

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

installyarn add react-stately
version3.30.1
usageimport {useDateFieldState} from 'react-stately'

API#


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

Interface#


Properties

NameTypeDescription
valueDateValueThe current field value.
dateValueDateThe current value, converted to a native JavaScript Date object.
calendarCalendarThe calendar system currently in use.
segmentsDateSegment[]A list of segments for the current value.
dateFormatterDateFormatterA date formatter configured for the current locale and format.
isInvalidbooleanWhether the date field is invalid, based on the isInvalid, minValue, and maxValue props.
granularityGranularityThe granularity for the field, based on the granularity prop and current value.
maxGranularity'year''month'GranularityThe maximum date or time unit that is displayed in the field.
isDisabledbooleanWhether the field is disabled.
isReadOnlybooleanWhether the field is read only.
isRequiredbooleanWhether the field is required.
realtimeValidationValidationResultRealtime validation results, updated as the user edits the value.
displayValidationValidationResultCurrently displayed validation results, updated when the user commits their changes.

Methods

MethodDescription
setValue( (value: DateValue )): voidSets the field's value.
increment( (type: SegmentType )): voidIncrements the given segment. Upon reaching the minimum or maximum value, the value wraps around to the opposite limit.
decrement( (type: SegmentType )): voidDecrements 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 )): voidSets the value of the given segment.
confirmPlaceholder(): voidUpdates the remaining unfilled segments with the placeholder value.
clearSegment( (type: SegmentType )): voidClears the value of the given segment, reverting it to the placeholder.
formatValue( (fieldOptions: FieldOptions )): stringFormats the current date value using the given options.
updateValidation( (result: ValidationResult )): voidUpdates the current validation result. Not displayed to the user until commitValidation is called.
resetValidation(): voidResets the displayed validation state to valid when the user resets the form.
commitValidation(): voidCommits the realtime validation so it is displayed to the user.

Example#


See the docs for useDateField in react-aria for an example of useDateFieldState.