The NumberInput
component is similar to the Input
component, but it has controls for incrementing or decrementing numeric values.
It follows the WAI-ARIA authoring practices for the Spinbutton widget.
Chakra UI exports 5 components for the NumberInput.
NumberInput
: The wrapper that provides context and logic to the components.NumberInputField
: The input
field itself.NumberInputStepper
: The wrapper for the input's stepper buttons.NumberIncrementStepper
: The button to increment the value of the input.NumberDecrementStepper
: The button to decrement the value of the input.The NumberInput
is composed of smaller components to give you control of the
styling of each part.
Pass the min
prop or max
prop to set an upper and lower limit for the input.
By default, the input will restrict the value to stay within the specified
range.
Pass the step
prop to change the step size when you increment or decrement the
value. By default, the value is rounded to match the number of decimals in the
step
.
In some cases, you might need the value to be rounded to specific decimal
points. Simply pass the precision
prop and set it to the number of decimal
points.
In most cases, users can type custom values in the input field. If the typed
value is greater than the max
, the value is reset to max
when the user blur
out of the input.
To disable this behavior, pass clampValueOnBlur
and set to false
.
In this example, try to type a value greater than the max. It won't reset the value on blur.
In some scenarios, you might not want to block out of range values. Pass the
keepWithinRange
and clampValueOnBlur
props and set them to false
to
support this use case.
The NumberInput will be set
isInvalid
totrue
internally when the value is out of range. Out of range means that thevalue
is great thanmax
or less thanmin
.
Like the Input
component, you can pass the size
prop to change the size of
the input.
You can change the style of any part of the components using style props. You can also change the icons used in the steppers.
A common use case is to combine the NumberInput
with a Slider
. Here's an
example of how to do that:
Sometimes, you might need to create a mobile version of the number input. Here's
how you can leverage the useNumberInput
hook to build one.
The NumberInput
component supports the ability to increment or decrement
values using the mouse wheel events. To activate this, pass the
allowMouseWheel
prop.
role
set to spinbutton
to denote that users are to select
from a range of discrete values using an up and down arrows on the keyboard.aria-valuemin
set to the minimum value allowed for the
spinbutton.aria-valuemax
set to the maximum value allowed for the
spinbutton. attribute should be applied to the spinbutton.aria-valuenow
set to the current value of the input
.aria-hidden
set to true
to
make them invisible to screen readers.step
.10 * step
.NumberInput composes Flex
with some additional props listed below.
Name | Type | Description | Default |
---|---|---|---|
allowMouseWheel | boolean | If `true`, the input's value will change based on mouse wheel | - |
clampValueOnBlur | boolean | This controls the value update when you blur out of the input. - If `true` and the value is greater than `max`, the value will be reset to `max` - Else, the value remains the same. | true |
colorScheme | string | - | |
defaultValue | string | number | The initial value of the counter. Should be less than `max` and greater than `min` | - |
errorBorderColor | string | The border color when the input is invalid. Use color keys in `theme.colors` @example errorBorderColor = "red.500" | - |
focusBorderColor | string | The border color when the input is focused. Use color keys in `theme.colors` @example focusBorderColor = "blue.500" | - |
focusInputOnChange | boolean | If `true`, the input will be focused as you increment or decrement the value with the stepper | true |
getAriaValueText | ((value: ReactText) => string) | This is used to format the value so that screen readers can speak out a more human-friendly value. It is used to set the `aria-valuetext` property of the input | - |
id | string | The `id` to use for the number input field. | - |
inputMode | "text" | "none" | "search" | "tel" | "url" | "email" | "numeric" | "decimal" | Hints at the type of data that might be entered by the user. It also determines the type of keyboard shown to the user on mobile devices | "decimal" |
isDisabled | boolean | If `true`, the input will be disabled | - |
isFullWidth | boolean | If `true`, the input element will span the full width of its parent | - |
isInvalid | boolean | If `true`, the input will have `aria-invalid` set to `true` | - |
isReadOnly | boolean | If `true`, the input will be in readonly mode | - |
keepWithinRange | boolean | This controls the value update behavior in general. - If `true` and you use the stepper or up/down arrow keys, the value will not exceed the `max` or go lower than `min` - If `false`, the value will be allowed to go out of range. | true |
max | number | The maximum value of the counter | Infinity |
min | number | The minimum value of the counter | -Infinity |
onChange | ((valueAsString: string, valueAsNumber: number) => void) | The callback fired when the value changes | - |
pattern | string | The pattern used to check the <input> element's value against on form submission. | "[0-9]*(.[0-9]+)?" |
precision | number | The number of decimal points used to round the value | - |
size | string | - | |
step | number | The step used to increment or decrement the value | 1 |
value | string | number | The value of the counter. Should be less than `max` and greater than `min` | - |
variant | string | - |
NumberInput
composes Input
so you can pass all Input
props.
NumberInputStepper
composes Flex
so you can pass all Flex
props.
NumberDecrementStepper
and NumberIncrementStepper
composes the Box
props
so you can pass all Box
props.