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.

install	`yarn add react-stately`
version	3.17.0
usage	`import {useNumberFieldState} from 'react-stately'`

View repository

GitHub

View package

NPM

API#

useNumberFieldState(
  (props: NumberFieldStateOptions
)): NumberFieldState

Interface#

Properties

Name	Type	Description
`inputValue`	`string`	The current text value of the input. Updated as the user types, and formatted according to `formatOptions` on blur.
`numberValue`	`number`	The currently parsed number value, or NaN if a valid number could not be parsed. Updated based on the `inputValue` as the user types.
`minValue`	`number`	The minimum value of the number field.
`maxValue`	`number`	The maximum value of the number field.
`canIncrement`	`boolean`	Whether the current value can be incremented according to the maximum value and step.
`canDecrement`	`boolean`	Whether the current value can be decremented according to the minimum value and step.

Methods

Method	Description
`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 )): void`	Sets 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(): void`	Increments the current input value to the next step boundary, and fires `onChange`.
`decrement(): void`	Decrements the current input value to the next step boundary, and fires `onChange`.
`incrementToMax(): void`	Sets the current value to the `maxValue` if any, and fires `onChange`.
`decrementToMin(): void`	Sets 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.

Name	Type	Default	Description
`locale`	`string`	`'en-US'`	The locale that should be used for parsing.
`formatOptions`	`Intl.NumberFormatOptions`	—	Formatting options for the value displayed in the number field. This also affects what characters are allowed to be typed by the user.
`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.
`placeholder`	`string`	—	Temporary text that occupies the text input when it is empty.
`value`	`number`	—	The current value (controlled).
`defaultValue`	`number`	—	The default value (uncontrolled).
`onChange`	`( (value: T )) => void`	—	Handler that is called when the value changes.
`minValue`	`number`	—	The smallest value allowed for the input.
`maxValue`	`number`	—	The largest value allowed for the input.
`step`	`number`	—	The amount that the input value changes with each increment or decrement "tick".
`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.

'valid' | 'invalid'

BaseEvent<ReactKeyboardEvent<any>>

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

Properties

Name	Type	Description
`inputValue`	`string`	The current text value of the input. Updated as the user types, and formatted according to `formatOptions` on blur.
`numberValue`	`number`	The currently parsed number value, or NaN if a valid number could not be parsed. Updated based on the `inputValue` as the user types.
`minValue`	`number`	The minimum value of the number field.
`maxValue`	`number`	The maximum value of the number field.
`canIncrement`	`boolean`	Whether the current value can be incremented according to the maximum value and step.
`canDecrement`	`boolean`	Whether the current value can be decremented according to the minimum value and step.

Methods

Method	Description
`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 )): void`	Sets 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(): void`	Increments the current input value to the next step boundary, and fires `onChange`.
`decrement(): void`	Decrements the current input value to the next step boundary, and fires `onChange`.
`incrementToMax(): void`	Sets the current value to the `maxValue` if any, and fires `onChange`.
`decrementToMin(): void`	Sets the current value to the `minValue` if any, and fires `onChange`.