Number Input

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.

Import#

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.
import {
NumberInput,
NumberInputField,
NumberInputStepper,
NumberIncrementStepper,
NumberDecrementStepper,
} from "@chakra-ui/react"

Usage#

The NumberInput is composed of smaller components to give you control of the styling of each part.

Editable Example

Setting a minimum and maximum value#

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.

Editable Example

Setting the step size#

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.

Editable Example

Adjusting the precision of the value#

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.

Editable Example

Clamp value when user blurs the input#

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.

Editable Example

Allowing out of range values#

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 to true internally when the value is out of range. Out of range means that the value is great than max or less than min.

Editable Example

Formatting and Parsing the value#

Editable Example

Changing the size of the input#

Like the Input component, you can pass the size prop to change the size of the input.

Editable Example

Changing the styles#

You can change the style of any part of the components using style props. You can also change the icons used in the steppers.

Editable Example

Combining it with a Slider#

A common use case is to combine the NumberInput with a Slider. Here's an example of how to do that:

0
Editable Example

Create a mobile spinner#

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.

Editable Example

Increment value using Mouse wheel#

The NumberInput component supports the ability to increment or decrement values using the mouse wheel events. To activate this, pass the allowMouseWheel prop.

Editable Example

Accessibility#

Aria Roles#

  • The input has 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.
  • The input has aria-valuemin set to the minimum value allowed for the spinbutton.
  • The input has aria-valuemax set to the maximum value allowed for the spinbutton. attribute should be applied to the spinbutton.
  • The input has aria-valuenow set to the current value of the input.
  • The custom spinner (up and down buttons) has aria-hidden set to true to make them invisible to screen readers.

Keyboard Navigation#

  • When you hit the or key, the input value will be increased or decreased by step.
  • Holding down Shift and pressing or will update the value by 10 * step.
  • Holding down Ctrl or , and pressing or will update the value by `0.1 * step`.
  • Long pressing the up and down stepper buttons will update the value at intervals.

Props#

NumberInput Props#

NumberInput composes Flex with some additional props listed below.

NameTypeDescriptionDefault
allowMouseWheelbooleanIf `true`, the input's value will change based on mouse wheel-
clampValueOnBlurbooleanThis 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
colorSchemestring-
defaultValuestring | numberThe initial value of the counter. Should be less than `max` and greater than `min`-
errorBorderColorstringThe border color when the input is invalid. Use color keys in `theme.colors` @example errorBorderColor = "red.500"-
focusBorderColorstringThe border color when the input is focused. Use color keys in `theme.colors` @example focusBorderColor = "blue.500"-
focusInputOnChangebooleanIf `true`, the input will be focused as you increment or decrement the value with the steppertrue
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-
idstringThe `id` to use for the number input field.-
inputMode"text" | "none" | "tel" | "url" | "email" | "numeric" | "decimal" | "search"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"
isDisabledbooleanIf `true`, the input will be disabled-
isFullWidthbooleanIf `true`, the input element will span the full width of its parent-
isInvalidbooleanIf `true`, the input will have `aria-invalid` set to `true`-
isReadOnlybooleanIf `true`, the input will be in readonly mode-
keepWithinRangebooleanThis 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
maxnumberThe maximum value of the counterInfinity
minnumberThe minimum value of the counter-Infinity
namestringThe HTML `name` attribute used for forms-
onChange((valueAsString: string, valueAsNumber: number) => void)The callback fired when the value changes-
patternstringThe pattern used to check the <input> element's value against on form submission."[0-9]*(.[0-9]+)?"
precisionnumberThe number of decimal points used to round the value-
sizestring-
stepnumberThe step used to increment or decrement the value1
valuestring | numberThe value of the counter. Should be less than `max` and greater than `min`-
variantstring-

NumberInputField Props#

NumberInput composes Input so you can pass all Input props.

NumberInputStepper Props#

NumberInputStepper composes Flex so you can pass all Flex props.

NumberDecrementStepper and NumberIncrementStepper Props#

NumberDecrementStepper and NumberIncrementStepper composes the Box props so you can pass all Box props.

Edit this page