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.42.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.
`defaultNumberValue`	`number`	The default value of the input.
`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.
`realtimeValidation`	`ValidationResult`	Realtime validation results, updated as the user edits the value.
`displayValidation`	`ValidationResult`	Currently displayed validation results, updated when the user commits their changes.
`minValue`	`number`	The minimum value of the number field.
`maxValue`	`number`	The maximum value of the number field.

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.
`setNumberValue( (val: number )): void`	Sets 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(): 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`.
`updateValidation( (result: ValidationResult )): void`	Updates the current validation result. Not displayed to the user until `commitValidation` is called.
`resetValidation(): void`	Resets the displayed validation state to valid when the user resets the form.
`commitValidation(): void`	Commits the realtime validation so it is displayed to the user.

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.
`isRequired`	`boolean`	—	Whether user input is required on the input before form submission.
`isInvalid`	`boolean`	—	Whether the input value is invalid.
`validationBehavior`	`'aria' \| 'native'`	`'aria'`	Whether to use native HTML form validation to prevent form submission when the value is missing or invalid, or mark the field as required or invalid via ARIA.
`validate`	`( (value: number )) => ValidationError \| true \| null \| undefined`	—	A function that returns an error message if a given value is invalid. Validation errors are displayed to the user when the form is submitted if `validationBehavior="native"`. For realtime validation, use the `isInvalid` prop instead.
`autoFocus`	`boolean`	—	Whether the element should receive focus on render.
`onFocus`	`( (e: FocusEvent<Target> )) => void`	—	Handler that is called when the element receives focus.
`onBlur`	`( (e: FocusEvent<Target> )) => 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 \| ( (v: ValidationResult )) => ReactNode`	—	An error message for the field.

'valid' | 'invalid'

string | string[]

BaseEvent<ReactKeyboardEvent<any>>

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

Name	Type	Description
`isInvalid`	`boolean`	Whether the input value is invalid.
`validationErrors`	`string[]`	The current error messages for the input if it is invalid, otherwise an empty array.
`validationDetails`	`ValidityState`	The native validation details for the input.

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.
`defaultNumberValue`	`number`	The default value of the input.
`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.
`realtimeValidation`	`ValidationResult`	Realtime validation results, updated as the user edits the value.
`displayValidation`	`ValidationResult`	Currently displayed validation results, updated when the user commits their changes.
`minValue`	`number`	The minimum value of the number field.
`maxValue`	`number`	The maximum value of the number field.

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.
`setNumberValue( (val: number )): void`	Sets 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(): 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`.
`updateValidation( (result: ValidationResult )): void`	Updates the current validation result. Not displayed to the user until `commitValidation` is called.
`resetValidation(): void`	Resets the displayed validation state to valid when the user resets the form.
`commitValidation(): void`	Commits the realtime validation so it is displayed to the user.