useNumberField

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

Price

Example

NumberField.tsx

NumberField.css

Button.css

Form.css

Example

NumberField.tsx

NumberField.css

Button.css

Form.css

import {NumberField} from './NumberField';

<NumberField label="Price" defaultValue={6} formatOptions={{style: 'currency', currency: 'USD'}} />

API

<NumberField>
  <Label />
  <Group>
    <Input />
    <Button slot="increment" />
    <Button slot="decrement" />
  </Group>
  <Text slot="description" />
  <FieldError />
</NumberField>

useNumberFieldState(props: NumberFieldStateOptions): NumberFieldState

useNumberField(
  props: AriaNumberFieldProps,
state: NumberFieldState,
inputRef: RefObject<HTMLInputElement | null>
): NumberFieldAria

NumberFieldState

Properties

Name	Type
`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.

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

Methods

`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(value?: string): 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.

AriaNumberFieldProps

Name	Type	Default
`decrementAriaLabel`	`string`	Default: —
A custom aria-label for the decrement button. If not provided, the localized string "Decrement" is used.
`incrementAriaLabel`	`string`	Default: —
A custom aria-label for the increment button. If not provided, the localized string "Increment" is used.
`isWheelDisabled`	`boolean`	Default: —
Enables or disables changing the value with scroll.
`commitBehavior`	`'snap' \| 'validate'`	Default: `'snap'`
Controls the behavior of the number field when the user blurs the field after editing. 'snap' will clamp the value to the min/max values, and snap to the nearest step value. 'validate' will not clamp the value, and will validate that the value is within the min/max range and on a valid step.
`isDisabled`	`boolean`	Default: —
Whether the input is disabled.
`isReadOnly`	`boolean`	Default: —
Whether the input can be selected but not changed by the user.
`placeholder`	`string`	Default: —
Temporary text that occupies the text input when it is empty.

`value`	`number`	Default: —
The current value (controlled).
`defaultValue`	`number`	Default: —
The default value (uncontrolled).
`onChange`	`(value: T) => void`	Default: —
Handler that is called when the value changes.
`formatOptions`	`Intl.NumberFormatOptions`	Default: —
Formatting options for the value displayed in the number field. This also affects what characters are allowed to be typed by the user.

NumberFieldAria

Name	Type
`labelProps`	`LabelHTMLAttributes<HTMLLabelElement>`
Props for the label element.
`groupProps`
Props for the group wrapper around the input and stepper buttons.
`inputProps`	`InputHTMLAttributes<HTMLInputElement>`
Props for the input element.
`incrementButtonProps`	`AriaButtonProps`
Props for the increment button, to be passed to `useButton`.
`decrementButtonProps`	`AriaButtonProps`
Props for the decrement button, to be passed to `useButton`.
`descriptionProps`	`DOMAttributes`
Props for the number field's description element, if any.
`errorMessageProps`	`DOMAttributes`
Props for the number field's error message element, if any.
`validationDetails`	`ValidityState`
The native validation details for the input.