---
title: NumberInput
description: "`NumberInput` is a component used to obtain numeric input from the user."
links:
  - style: https://github.com/yamada-ui/yamada-ui/tree/main/packages/react/src/components/number-input/number-input.style.ts
  - source: https://github.com/yamada-ui/yamada-ui/tree/main/packages/react/src/components/number-input
  - storybook: https://yamada-ui.github.io/yamada-ui?path=/story/components-numberinput--basic
---

```tsx
<NumberInput placeholder="placeholder" />
```

## Usage

```tsx
import { NumberInput } from "@yamada-ui/react"
```

```tsx
import { NumberInput } from "@/components/ui"
```

```tsx
import { NumberInput } from "@workspaces/ui"
```

```tsx
<NumberInput />
```

### Change Variant

```tsx
<VStack>
  <For each={["outline", "filled", "flushed"]}>
    {(variant) => (
      <NumberInput
        key={variant}
        variant={variant}
        placeholder={toTitleCase(variant)}
      />
    )}
  </For>
</VStack>
```

### Change Size

```tsx preview
<VStack>
  <For each={["xs", "sm", "md", "lg", "xl"]}>
    {(size) => (
      <NumberInput key={size} size={size} placeholder={`Size (${size})`} />
    )}
  </For>
</VStack>
```

### Set Default Value

To set a default value, set a string or number to `defaultValue`.

```tsx
<NumberInput defaultValue={18} placeholder="Order Quantity" />
```

### Set Minimum and Maximum Values

To set minimum and maximum values, set a number to `min` or `max`.

```tsx
<NumberInput defaultValue={18} min={8} max={31} placeholder="Order Quantity" />
```

### Set Step Value

To set a step value, set a number to `step`.

```tsx
<NumberInput
  defaultValue={15}
  step={5}
  min={5}
  max={30}
  placeholder="Order Quantity"
/>
```

### Set Decimal Points

To set decimal points, set a number to `precision`.

```tsx
<NumberInput
  defaultValue={15}
  precision={2}
  step={0.2}
  placeholder="Order Quantity"
/>
```

### Disable Clamping Value on Blur

By default, the component accepts any numeric input from the user, but values exceeding `min` or `max` are automatically adjusted on blur. To disable this automatic adjustment, set `clampValueOnBlur` to `false`.

```tsx
<NumberInput
  defaultValue={15}
  max={30}
  clampValueOnBlur={false}
  placeholder="Order Quantity"
/>
```

### Allow Out-of-Range Values

To allow out-of-range values, set `keepWithinRange` to `false`.

```tsx
<NumberInput
  defaultValue={15}
  max={30}
  keepWithinRange={false}
  clampValueOnBlur={false}
  placeholder="Order Quantity"
/>
```

### Disable

To disable the component, set `disabled` to `true`.

```tsx
<VStack>
  <For each={["outline", "filled", "flushed"]}>
    {(variant) => (
      <NumberInput
        key={variant}
        disabled
        variant={variant}
        placeholder={toTitleCase(variant)}
      />
    )}
  </For>
</VStack>
```

### Read-Only

To make the component read-only, set `readOnly` to `true`.

```tsx
<VStack>
  <For each={["outline", "filled", "flushed"]}>
    {(variant) => (
      <NumberInput
        key={variant}
        readOnly
        variant={variant}
        placeholder={toTitleCase(variant)}
      />
    )}
  </For>
</VStack>
```

### Invalid

To make invalid, set `invalid` to `true`.

```tsx
<VStack>
  <For each={["outline", "filled", "flushed"]}>
    {(variant) => (
      <NumberInput
        key={variant}
        invalid
        variant={variant}
        placeholder={toTitleCase(variant)}
      />
    )}
  </For>
</VStack>
```

### Change Border Color

To change the border color, set a color to `focusBorderColor` or `errorBorderColor`.

```tsx
<VStack>
  <NumberInput
    focusBorderColor="green.500"
    placeholder="Custom focus border color"
  />
  <NumberInput
    errorBorderColor="orange.500"
    invalid
    placeholder="Custom invalid border color"
  />
</VStack>
```

### Change Placeholder Color

To change the placeholder color, set `_placeholder` to the value.

```tsx
<NumberInput
  placeholder="Custom placeholder"
  _placeholder={{ color: "blue.500" }}
/>
```

### Customize Stepper

To customize the stepper, set props to `incrementProps` or `decrementProps`.

```tsx
<NumberInput
  placeholder="Order Quantity"
  incrementProps={{ children: <PlusIcon /> }}
  decrementProps={{ children: <MinusIcon /> }}
/>
```

### Customize Component

To customize the component, use `useNumberInput`.

```tsx
const { getInputProps, getIncrementProps, getDecrementProps } = useNumberInput({
  step: 0.01,
  defaultValue: 3.14,
  min: 3,
  max: 4,
  precision: 2,
})

return (
  <HStack maxW="xs" gap="sm">
    <IconButton
      icon={<PlusIcon fontSize="2xl" />}
      {...getIncrementProps()}
      aria-label="Increment"
    />
    <Input {...getInputProps()} aria-label="Number Input" />
    <IconButton
      icon={<MinusIcon fontSize="2xl" />}
      {...getDecrementProps()}
      aria-label="Decrement"
    />
  </HStack>
)
```

### Control

```tsx
const [value, setValue] = useState(18)

return (
  <NumberInput
    value={value}
    onChange={(_, valueAsNumber) => setValue(valueAsNumber)}
    placeholder="Order Quantity"
  />
)
```

## Props

| Prop                 | Default                   | Type                                                                                                                                                              | Description                                                                                                                                                                                                                            |
| -------------------- | ------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `as`                 | -                         | `As`                                                                                                                                                              | The HTML element to render.                                                                                                                                                                                                            |
| `asChild`            | -                         | `boolean`                                                                                                                                                         | Merges its props onto its immediate child.                                                                                                                                                                                             |
| `css`                | -                         | `CSSObject \| CSSObject[]`                                                                                                                                        | The CSS object.                                                                                                                                                                                                                        |
| `colorScheme`        | -                         | `"amber" \| "black" \| "blackAlpha" \| "blue" \| "cyan" \| "danger" \| "emerald" \| "error" \| "flashy" \| "fuchsia" ...`                                         | Set color scheme variables.                                                                                                                                                                                                            |
| `size`               | `"md"`                    | `"2xl" \| "lg" \| "md" \| "sm" \| "xl" \| "xs"`                                                                                                                   | The size of the component.                                                                                                                                                                                                             |
| `variant`            | `"outline"`               | `"filled" \| "flushed" \| "outline" \| "plain"`                                                                                                                   | The variant of the component.                                                                                                                                                                                                          |
| `allowMouseWheel`    | `false`                   | `boolean`                                                                                                                                                         | If `true`, the input's value will change based on mouse wheel.                                                                                                                                                                         |
| `clampValueOnBlur`   | `true`                    | `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.                                                  |
| `controlProps`       | -                         | `NumberInputControlProps`                                                                                                                                         | The props for the control element.                                                                                                                                                                                                     |
| `decrementProps`     | -                         | `NumberInputDecrementButtonProps`                                                                                                                                 | The props for the decrement button element.                                                                                                                                                                                            |
| `defaultValue`       | -                         | `number \| string`                                                                                                                                                | The initial value of the counter. Should be less than `max` and greater than `min`.                                                                                                                                                    |
| `elementProps`       | -                         | `InputGroup.ElementProps`                                                                                                                                         | The props for the end element.                                                                                                                                                                                                         |
| `errorBorderColor`   | -                         | `"-moz-initial" \| "ActiveBorder" \| "ActiveCaption" \| "aliceblue" \| "amber.100" \| "amber.200" \| "amber.300" \| "amber.400" \| "amber.50" \| "amber.500" ...` | The border color when the input is invalid.                                                                                                                                                                                            |
| `focusBorderColor`   | -                         | `"-moz-initial" \| "ActiveBorder" \| "ActiveCaption" \| "aliceblue" \| "amber.100" \| "amber.200" \| "amber.300" \| "amber.400" \| "amber.50" \| "amber.500" ...` | The border color when the input is focused.                                                                                                                                                                                            |
| `focusInputOnChange` | `true`                    | `boolean`                                                                                                                                                         | If `true`, the input will be focused as you increment or decrement the value with the button.                                                                                                                                          |
| `format`             | -                         | `(value: number \| string) => string`                                                                                                                             | If using a custom display format, this converts the default format to the custom format.                                                                                                                                               |
| `getAriaValueText`   | -                         | `(value: number \| string) => string \| undefined`                                                                                                                | 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.                                                                       |
| `htmlSize`           | -                         | `number`                                                                                                                                                          | The native HTML `size` attribute to be passed to the `input`.                                                                                                                                                                          |
| `incrementProps`     | -                         | `NumberInputIncrementButtonProps`                                                                                                                                 | The props for the increment button element.                                                                                                                                                                                            |
| `invalid`            | `false`                   | `boolean`                                                                                                                                                         | If `true`, the field will be invalid.                                                                                                                                                                                                  |
| `isValidCharacter`   | -                         | `(value: string) => boolean`                                                                                                                                      | Whether the pressed key should be allowed in the input. The default behavior is to allow DOM floating point characters defined by /^[Ee0-9+\-.]$/.                                                                                     |
| `keepWithinRange`    | `true`                    | `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. |
| `max`                | `Number.MAX_SAFE_INTEGER` | `number`                                                                                                                                                          | The maximum value of the counter                                                                                                                                                                                                       |
| `min`                | `Number.MIN_SAFE_INTEGER` | `number`                                                                                                                                                          | The minimum value of the counter                                                                                                                                                                                                       |
| `onChange`           | -                         | `(valueAsString: string, valueAsNumber: number) => void`                                                                                                          | The callback fired when the value changes.                                                                                                                                                                                             |
| `parse`              | -                         | `(value: string) => string`                                                                                                                                       | If using a custom display format, this converts the custom format to a format `parseFloat` understands.                                                                                                                                |
| `precision`          | -                         | `number`                                                                                                                                                          | The number of decimal points used to round the value.                                                                                                                                                                                  |
| `rootProps`          | -                         | `InputGroup.RootProps`                                                                                                                                            | The props for the root element.                                                                                                                                                                                                        |
| `step`               | `1`                       | `number`                                                                                                                                                          | The step used to increment or decrement the value.                                                                                                                                                                                     |
| `value`              | -                         | `number \| string`                                                                                                                                                | The value of the counter. Should be less than `max` and greater than `min`.                                                                                                                                                            |

## Accessibility

Currently, this section is being updated due to the migration of v2.