useNumberFieldState

Provides state management for a number field component. Number fields allow users to enter a number, and increment or decrement the value using stepper buttons.

installyarn add react-stately
version3.32.2
usageimport {useNumberFieldState} from 'react-stately'

API#


useNumberFieldState( (props: NumberFieldStateOptions )): NumberFieldState

Interface#


Properties

NameTypeDescription
inputValuestring

The current text value of the input. Updated as the user types, and formatted according to formatOptions on blur.

numberValuenumber

The currently parsed number value, or NaN if a valid number could not be parsed. Updated based on the inputValue as the user types.

canIncrementbooleanWhether the current value can be incremented according to the maximum value and step.
canDecrementbooleanWhether the current value can be decremented according to the minimum value and step.
realtimeValidationValidationResultRealtime validation results, updated as the user edits the value.
displayValidationValidationResultCurrently displayed validation results, updated when the user commits their changes.
minValuenumberThe minimum value of the number field.
maxValuenumberThe maximum value of the number field.

Methods

MethodDescription
validate( (value: string )): boolean

Validates a user input string according to the current locale and format options. Values can be partially entered, and may be valid even if they cannot currently be parsed to a number. Can be used to implement validation as a user types.

setInputValue( (val: string )): voidSets the current text value of the input.
setNumberValue( (val: number )): voidSets the number value.
commit(): void

Commits the current input value. The value is parsed to a number, clamped according to the minimum and maximum values of the field, and snapped to the nearest step value. This will fire the onChange prop with the new value, and if uncontrolled, update the numberValue. Typically this is called when the field is blurred.

increment(): voidIncrements the current input value to the next step boundary, and fires onChange.
decrement(): voidDecrements the current input value to the next step boundary, and fires onChange.
incrementToMax(): voidSets the current value to the maxValue if any, and fires onChange.
decrementToMin(): voidSets the current value to the minValue if any, and fires onChange.
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 useNumberField in react-aria for an example of useNumberFieldState.