Number Input


Chakra Docs


⦾ Number input fields are a common element in web forms that allow users to input numeric values. They are used for various purposes, such as capturing quantities, prices, measurements, or any other numerical data. Chakra UI provides a dedicated set of components called NumberInput to facilitate the creation of number input fields with enhanced functionality and styling.

  • NumberInput: This component serves as the main wrapper and provides the context and logic for the number input components. It manages the state and behavior of the number input as a whole.
  • NumberInputField: This represents the actual input field where users can enter numeric values. It handles user input and stores the entered value.
  • NumberInputStepper: This component acts as a wrapper for the stepper buttons associated with the number input. It provides a container for the increment and decrement buttons, allowing users to adjust the value of the input.
  • NumberIncrementStepper: The NumberIncrementStepper component is the button responsible for incrementing the value of the number input. When clicked, it increases the value by a specified step size.
  • NumberDecrementStepper: Conversely, the NumberDecrementStepper component serves as the button to decrement the value of the number input. It reduces the value by a specified step size when clicked.

By utilizing the NumberInput components from Chakra UI, you can easily create number input fields with enhanced functionality and a consistent visual appearance. The modular nature of these components allows for customization and flexibility while maintaining a seamless user experience.

These components can be imported as follows:


Basic Usage

⦾ To use the NumberInput component, you can wrap it around its subcomponents to create a complete input field with increment and decrement buttons.


Setting Limits

⦾ If you want to restrict the value entered within a specific range, you can utilize the min and max props. By setting the min prop, you define the lower limit, and by setting the max prop, you define the upper limit. The NumberInput component will then ensure that the value stays within the specified range.

The following example has a min set to 23 and a max set to 53, so if you enter a value that is not between the limits, it will automatically be adjusted to the closest limit.


Customizing Increment and Decrement

⦾ If you want to customize the increment or decrement step when changing the value, you can use the step prop. By passing a value to the step prop, you can define the size of each step. By default, the value is rounded to match the number of decimals in the step.

In the following example, the step size is set to 10, with a low end limit of 10 and a high end limit of 500.


Adjusting Precision

⦾ There might be cases where you need the value to be rounded to a specific number of decimal points. To achieve this, you can use the precision prop. By passing the precision prop and setting it to the desired number of decimal points, theNumberInput component will automatically round the value accordingly.

In the following example, the NumberInput component is configured with a default value of 23, a precision of 3 decimal points, and a step of 0.3. This means that the input value will be rounded to three decimal points, and each increment or decrement will change the value by 0.3.



⦾ By default, when a user types a value that exceeds the maximum limit (max), the value is reset to the maximum value when the user moves away from the input field (on blur). To disable this behavior, you can use the clampValueOnBlur prop and set it to false.

Instead of adjusting the value within the pre-defined limits, the input field will display an error outline. In the following example, the max is set to 123, and the minimum is at 23, the initial default value.


Value Ranges

⦾ In some cases, you may want to allow values that exceed the defined range. By using the keepWithinRange and clampValueOnBlur props and setting them to false, you can support this use case. When the value goes beyond the specified range (greater than max or less than min), the NumberInput component will internally set the isInvalid prop to true.

In the following example, the max is set to 123, and the minimum is at 23. But the keepWithinRange and clampValueOnBlur props are set to false. This means that the user may enter a range that exceeds the defined limits.


Formating Values

⦾ The NumberInput component allows you to format and parse the value according to your needs. You can provide custom formatting and parsing functions using the format and parse functions. The format function formats the value for display, while the parse function converts the formatted value back to its original form.

The following example includes a format function that adds a $ sign before the value and a parse function that removes the $ sign from the value. The initial value is set to '1.23', and whenever the value changes, the onChange function updates the state after parsing the value.


Input Size

⦾ Similar to the Input component, you can adjust the size of the NumberInput component using the size prop. By providing different size values such as 'xs', 'sm', 'md', or 'lg', you can control the visual size of the input field.

Here is a visual representation of these options:



⦾ You have the flexibility to customize the styles of various parts of the NumberInput component. By using style props such as borderColor, bg, and _active, you can modify the appearance of the input field and the stepper buttons. Additionally, you can change the icons used in the increment and decrement buttons by specifying custom children.


Mobile Number Input

⦾ If you need to create a mobile version of a number input, you can utilize the useNumberInput hook to build one. This hook provides convenient functions to handle the increment, decrement, and input functionalities.

In the following example, the HookUsage component uses the useNumberInput hook to manage the state and behaviors of the number input. The hook is configured with various options such asstep, defaultValue, min, max, and precision. The getIncrementButtonProps, getDecrementButtonProps, and getInputProps functions are used to retrieve the necessary props for the increment button, decrement button, and input field, respectively. These props are then spread onto the corresponding components (Button and Input) to enable the increment, decrement, and input functionalities.


Incorporating a Slider

⦾ The following two examples show two different ways you can integrate a number input with a slider component.

This first example utilizes the useNumberInput hook from to manage the number input functionality. The value state is managed using useState and is initially set to the input value. Additionally, an effect is used to update the value state whenever the input value changes. The handleSliderChange function ensures synchronization between the Slider and the value state.



This following version manages the value state using useState, initializing it to 0. The handleChange function handles the updates to the value state when the NumberInput or Slider values change. The value prop of both the NumberInput and Slider is set to the value state, ensuring synchronization between them. The focusThumbOnChange prop of the Slider is set to false to prevent the Slider thumb from losing focus when the input value changes.



Both components above achieve the goal of combining a NumberInput and Slider, but with different approaches. The first example relies on the useNumberInput hook for managing the number input functionality, while second directly handles state management using useState. The former employs the useEffect hook to synchronize the value state with the input value, while the latter uses a single handleChange function to keep the value state in sync between the NumberInput and Slider.

Mouse Scroll Control

⦾ This example shows how to enable the increment and decrement functionality using the mouse wheel events. The allowMouseWheel prop is set to true to activate this feature.


Did you know?

Creative Idea No. 1

Dynamic Font Size Control: The NumberInput can be used to dynamically control the font size of a text element. By adjusting the numerical value in the NumberInput, the font size of the associated text will increase or decrease accordingly. In the example below, a user can increment or decrement the font size to anything between 10 and 35 pixels. The current font size is stored in the fontSize state variable. The handleChange function is invoked whenever the value in the NumberInput changes, updating the fontSize state. The font size of the text element is dynamically updated based on the value of fontSize.

Font Size:

Adjustable Text Size


Creative Idea No. 2

Image Opacity Control: The NumberInput can be used to adjust the opacity of an image. By changing the numerical value in the NumberInput, the opacity of the image will be modified in real-time. The current opacity value is stored in the opacity state variable. The handleChange function is called whenever the value in the NumberInput changes, updating the opacity state. The opacity of the image is adjusted in real-time based on the value selected.


very precious bear


Creative Idea No. 3

Temperature Conversion: The NumberInput can be utilized to convert temperatures between Celsius and Fahrenheit. Users can enter a value in either Celsius or Fahrenheit, and the NumberInput will dynamically convert and display the corresponding temperature in the other unit. The current values in Celsius and Fahrenheit are stored in separate state variables, celsius and fahrenheit. When the Celsius value changes, the handleCelsiusChange function is called, updating both the celsius and fahrenheit states by performing the temperature conversion. Similarly, when the Fahrenheit value changes, the handleFahrenheitChange function is called, updating both the fahrenheit and celsius states by performing the reverse temperature conversion.


copyright © 2023 IHeartComponents |


Special thanks to Stefan Bohacek / Generative Placeholders.