---
id: number-input
category: form
title: Number Input
package: '@chakra-ui/number-input'
description:
  The NumberInput component is similar to the Input component, but it has
  controls for incrementing or decrementing numeric values.
---

## 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.

```js
import {
  NumberInput,
  NumberInputField,
  NumberInputStepper,
  NumberIncrementStepper,
  NumberDecrementStepper,
} from '@chakra-ui/react'
```

## Usage

The NumberInput component follows the
[WAI-ARIA authoring practices](https://www.w3.org/TR/wai-aria-practices-1.1/#spinbutton)
for the spin button widget. It is composed of smaller components to give you
control of the styling of each part.

```jsx
<NumberInput>
  <NumberInputField />
  <NumberInputStepper>
    <NumberIncrementStepper />
    <NumberDecrementStepper />
  </NumberInputStepper>
</NumberInput>
```

### 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.

> These props defaults to
> [Number.MIN_SAFE_INTEGER](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number/MIN_SAFE_INTEGER)
> and
> [Number.MAX_SAFE_INTEGER](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number/MAX_SAFE_INTEGER)
> . If they do not match your requirements you can use other `Number` properties
> as `min` or `max`.

```jsx
<NumberInput defaultValue={15} min={10} max={20}>
  <NumberInputField />
  <NumberInputStepper>
    <NumberIncrementStepper />
    <NumberDecrementStepper />
  </NumberInputStepper>
</NumberInput>
```

### 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`.

```jsx
<NumberInput step={5} defaultValue={15} min={10} max={30}>
  <NumberInputField />
  <NumberInputStepper>
    <NumberIncrementStepper />
    <NumberDecrementStepper />
  </NumberInputStepper>
</NumberInput>
```

### 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.

```jsx
<NumberInput defaultValue={15} precision={2} step={0.2}>
  <NumberInputField />
  <NumberInputStepper>
    <NumberIncrementStepper />
    <NumberDecrementStepper />
  </NumberInputStepper>
</NumberInput>
```

### 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.

```jsx
<NumberInput defaultValue={15} max={30} clampValueOnBlur={false}>
  <NumberInputField />
  <NumberInputStepper>
    <NumberIncrementStepper />
    <NumberDecrementStepper />
  </NumberInputStepper>
</NumberInput>
```

### 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`.

```jsx
<NumberInput
  defaultValue={15}
  max={10}
  keepWithinRange={false}
  clampValueOnBlur={false}
>
  <NumberInputField />
  <NumberInputStepper>
    <NumberIncrementStepper />
    <NumberDecrementStepper />
  </NumberInputStepper>
</NumberInput>
```

### Formatting and Parsing the value

```jsx
function Example() {
  const format = (val) => `$` + val
  const parse = (val) => val.replace(/^\$/, '')

  const [value, setValue] = React.useState('1.53')

  return (
    <NumberInput
      onChange={(valueString) => setValue(parse(valueString))}
      value={format(value)}
      max={50}
    >
      <NumberInputField />
      <NumberInputStepper>
        <NumberIncrementStepper />
        <NumberDecrementStepper />
      </NumberInputStepper>
    </NumberInput>
  )
}
```

### Changing the size of the input

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

```jsx
<Stack shouldWrapChildren direction='row'>
  <NumberInput size='xs' maxW={16} defaultValue={15} min={10}>
    <NumberInputField />
    <NumberInputStepper>
      <NumberIncrementStepper />
      <NumberDecrementStepper />
    </NumberInputStepper>
  </NumberInput>

  <NumberInput size='sm' maxW={20} defaultValue={15} min={10}>
    <NumberInputField />
    <NumberInputStepper>
      <NumberIncrementStepper />
      <NumberDecrementStepper />
    </NumberInputStepper>
  </NumberInput>

  <NumberInput size='md' maxW={24} defaultValue={15} min={10}>
    <NumberInputField />
    <NumberInputStepper>
      <NumberIncrementStepper />
      <NumberDecrementStepper />
    </NumberInputStepper>
  </NumberInput>

  <NumberInput size='lg' maxW={32} defaultValue={15} min={10}>
    <NumberInputField />
    <NumberInputStepper>
      <NumberIncrementStepper />
      <NumberDecrementStepper />
    </NumberInputStepper>
  </NumberInput>
</Stack>
```

### 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.

```jsx
<NumberInput size='sm' defaultValue={15} min={10}>
  <NumberInputField focusBorderColor='red.200' />
  <NumberInputStepper>
    <NumberIncrementStepper
      bg='green.200'
      _active={{ bg: 'green.300' }}
      children='+'
    />
    <NumberDecrementStepper
      bg='pink.200'
      _active={{ bg: 'pink.300' }}
      children='-'
    />
  </NumberInputStepper>
</NumberInput>
```

### Combining it with a Slider

A common use case is to combine the `NumberInput` with a `Slider`.

We recommend disabling `focusThumbOnChange` on the `Slider`, so the
`NumberInput` won't lose focus after input.

Here's an example of how to do that:

```jsx
function SliderInput() {
  const [value, setValue] = React.useState(0)
  const handleChange = (value) => setValue(value)

  return (
    <Flex>
      <NumberInput maxW='100px' mr='2rem' value={value} onChange={handleChange}>
        <NumberInputField />
        <NumberInputStepper>
          <NumberIncrementStepper />
          <NumberDecrementStepper />
        </NumberInputStepper>
      </NumberInput>
      <Slider
        flex='1'
        focusThumbOnChange={false}
        value={value}
        onChange={handleChange}
      >
        <SliderTrack>
          <SliderFilledTrack />
        </SliderTrack>
        <SliderThumb fontSize='sm' boxSize='32px' children={value} />
      </Slider>
    </Flex>
  )
}
```

### 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.

```jsx
function HookUsage() {
  const { getInputProps, getIncrementButtonProps, getDecrementButtonProps } =
    useNumberInput({
      step: 0.01,
      defaultValue: 1.53,
      min: 1,
      max: 6,
      precision: 2,
    })

  const inc = getIncrementButtonProps()
  const dec = getDecrementButtonProps()
  const input = getInputProps()

  return (
    <HStack maxW='320px'>
      <Button {...inc}>+</Button>
      <Input {...input} />
      <Button {...dec}>-</Button>
    </HStack>
  )
}
```

### 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.

```jsx
function MouseWheelExample() {
  return (
    <NumberInput allowMouseWheel>
      <NumberInputField />
      <NumberInputStepper>
        <NumberIncrementStepper />
        <NumberDecrementStepper />
      </NumberInputStepper>
    </NumberInput>
  )
}
```

## 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 <kbd>⬆</kbd> or <kbd>⬇</kbd> key, the input value will be
  increased or decreased by `step`.
- Holding down <kbd>Shift</kbd> and pressing <kbd>⬆</kbd> or <kbd>⬇</kbd> will
  update the value by `10 * step`.
- Holding down <kbd>Ctrl</kbd> or <kbd>⌘</kbd>, and pressing <kbd>⬆</kbd> or
  <kbd>⬆</kbd> will update the value by `0.1 * step`.
- Long pressing the up and down stepper buttons will update the value at
  intervals.