NumberInput

NumberInput is a component used to obtain numeric input from the user.

<NumberInput placeholder="placeholder" />

Usage

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

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

import { NumberInput } from "@workspaces/ui"

<NumberInput />

Change Variant

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

Change Size

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

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

Set Minimum and Maximum Values

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

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

Set Step Value

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

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

Set Decimal Points

To set decimal points, set a number to precision.

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

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

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

Disable

To disable the component, set disabled to true.

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

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

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

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

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

Customize Stepper

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

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

Customize Component

To customize the component, use useNumberInput.

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

If you use this code, you need to add "use client" to the top of the file.

Control

const [value, setValue] = useState(18)

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

If you use this code, you need to add "use client" to the top of the file.

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" \| "AccentColor" \| "AccentColorText" \| "ActiveBorder" \| "ActiveCaption" \| "ActiveText" \| "aliceblue" \| "amber.100" \| "amber.200" \| "amber.300" ...` The border color when the input is invalid.
`focusBorderColor`	-	`"-moz-initial" \| "AccentColor" \| "AccentColorText" \| "ActiveBorder" \| "ActiveCaption" \| "ActiveText" \| "aliceblue" \| "amber.100" \| "amber.200" \| "amber.300" ...` 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

The NumberInput follows the WAI-ARIA - Spinbutton Pattern for accessibility.

If you are not using Field.Root, set aria-label or aria-labelledby to NumberInput.

<NumberInput aria-label="Age" />

<VStack gap="sm">
  <Text as="h3" id="label">
    Age
  </Text>

  <NumberInput aria-labelledby="label" />
</VStack>

Key	Description	State
`ArrowUp`	Increases the value based on `step` value.	-
`ArrowDown`	Decreases the value based on `step` value.	-
`Home`	Sets to `min` value.	-
`End`	Sets to `max` value.	-
`Shift` + `ArrowUp`	Increases the value by 10x the `step`.	-
`Shift` + `ArrowDown`	Decreases the value by 10x the `step`.	-
`Meta` + `ArrowUp`, `Ctrl` + `ArrowUp`	Increases the value by 0.1x the `step`.	-
`Meta` + `ArrowDown`, `Ctrl` + `ArrowDown`	Decreases the value by 0.1x the `step`.	-

ARIA Roles and Attributes

Component	Roles and Attributes	Usage
`NumberInput`	`role="spinbutton"`	Indicates that this is a spinbutton.
	`aria-valuemin`	Sets to `min` value.
	`aria-valuemax`	Sets to `max` value.
	`aria-valuenow`	Sets to current value.
	`aria-valuetext`	Sets to current value.
	`aria-invalid`	Sets to `"true"` if `invalid` is set or if the value is out of range.
	`aria-describedby`	If `NumberInput` is within a `Field.Root` and `Field.Root` has an `errorMessage`, `helperMessage`, or a `Field.ErrorMessage`, `Field.HelperMessage`, sets its `id`.
	`aria-disabled`	Sets to `"true"` if `disabled` is set.
	`aria-readonly`	Sets to `"true"` if `readOnly` is set.
	`aria-required`	Sets to `"true"` if `required` is set.
`NumberInputIncrementButton`	`aria-label`	Sets to `"Increase"`.
`NumberInputDecrementButton`	`aria-label`	Sets to `"Decrease"`.