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/numberfield
version3.0.6
usageimport {useNumberFieldState} from '@react-stately/numberfield'

API#


useNumberFieldState( (props: NumberFieldStateProps )): 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.

minValuenumberThe minimum value of the number field.
maxValuenumberThe maximum value of the number field.
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.

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

Example#


See the docs for useNumberField in react-aria for an example of useNumberFieldState.