Number Input

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.

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

Usage

The NumberInput component follows the WAI-ARIA authoring practices for the spin button widget. It is composed of smaller components to give you control of the styling of each part.

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

<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 and Number.MAX_SAFE_INTEGER . If they do not match your requirements you can use other Number properties as min or max.

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

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

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

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

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

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

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

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

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

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

Formatting and Parsing the value

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> ); }

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.

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

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

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

<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:

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> ); }

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.

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> ); }

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.

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

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

allowMouseWheel

Description

If true, the input's value will change based on mouse wheel

Type

boolean

aria-describedby

Type

string

aria-label

Type

string

aria-labelledby

Type

string

clampValueOnBlur

Description

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.

Type

boolean

Default

true

colorScheme

Description

Color Schemes for NumberInput are not implemented in the default theme. You can extend the theme to implement them.

Type

string

defaultValue

Description

The initial value of the counter. Should be less than max and greater than min

Type

string | number

errorBorderColor

Description

The border color when the input is invalid. Use color keys in `theme.colors` @example errorBorderColor = "red.500"

Type

string

focusBorderColor

Description

The border color when the input is focused. Use color keys in `theme.colors` @example focusBorderColor = "blue.500"

Type

string

focusInputOnChange

Description

If true, the input will be focused as you increment or decrement the value with the stepper

Type

boolean

Default

true

format

Description

If using a custom display format, this converts the default format to the custom format.

Type

((value: string | number) => string | number)

getAriaValueText

Description

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

Type

((value: string | number) => string)

id

Description

The id to use for the number input field.

Type

string

inputMode

Description

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

Type

"text" | "search" | "none" | "tel" | "url" | "email" | "numeric" | "decimal"

Default

"decimal"

isDisabled

Description

Whether the input should be disabled

Type

boolean

isInvalid

Description

If true, the input will have `aria-invalid` set to true

Type

boolean

isReadOnly

Description

If true, the input will be in readonly mode

Type

boolean

isRequired

Description

Whether the input is required

Type

boolean

isValidCharacter

Description

Whether the pressed key should be allowed in the input. The default behavior is to allow DOM floating point characters defined by /^[Ee0-9+\-.]$/

Type

((value: string) => boolean)

keepWithinRange

Description

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.

Type

boolean

Default

true

max

Description

The maximum value of the counter

Type

number

Default

Number.MAX_SAFE_INTEGER

min

Description

The minimum value of the counter

Type

number

Default

Number.MIN_SAFE_INTEGER

name

Description

The HTML name attribute used for forms

Type

string

onBlur

Type

FocusEventHandler<HTMLInputElement>

onChange

Description

The callback fired when the value changes

Type

((valueAsString: string, valueAsNumber: number) => void)

onFocus

Type

FocusEventHandler<HTMLInputElement>

onInvalid

Type

((message: ValidityState, value: string, valueAsNumber: number) => void)

parse

Description

If using a custom display format, this converts the custom format to a format parseFloat understands.

Type

((value: string) => string)

pattern

Description

The pattern used to check the <input> element's value against on form submission.

Type

string

Default

"[0-9]*(.[0-9]+)?"

precision

Description

The number of decimal points used to round the value

Type

number

size

Type

"xs" | "sm" | "md" | "lg"

Default

"md"

step

Description

The step used to increment or decrement the value

Type

number

Default

1

value

Description

The value of the counter. Should be less than max and greater than min

Type

string | number

variant

Type

"outline" | "filled" | "flushed" | "unstyled"

Default

"outline"

NumberInputField Props

NumberInputField composes Input so you can pass all Input props. If you want to change the size, pass the size prop to the NumberInput component instead, as demonstrated above.

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.