Forms

Number Input

Numeric field with steppers, clamping and keyboard control.

Import

tsx

import { NumberInput } from "@cooud-ui/ui";

bash

npx cooud-ui add number-input

Examples

Default

A spinbutton with increment/decrement steppers. Arrow keys step, PageUp/PageDown jump, and Home/End snap to `min`/`max`. Values are clamped to the bounds on blur.

Quantity

Between 0 and 10.

tsx

function NumberInputDemo() {
  const [quantity, setQuantity] = useState<number | null>(1);

  return (
    <Field className="max-w-[12rem]">
      <FieldLabel htmlFor="qty">Quantity</FieldLabel>
      <NumberInput
        id="qty"
        value={quantity}
        onValueChange={setQuantity}
        min={0}
        max={10}
        aria-label="Quantity"
      />
      <FieldDescription>Between 0 and 10.</FieldDescription>
    </Field>
  );
}

Precision & formatting

Use `precision` for decimal rounding and `format` to display a unit such as currency when the field is not focused.

tsx

function NumberInputCurrencyDemo() {
  const [price, setPrice] = useState<number | null>(19.9);

  return (
    <NumberInput
      value={price}
      onValueChange={setPrice}
      min={0}
      step={0.1}
      precision={2}
      format={(value) => `$${value.toFixed(2)}`}
      aria-label="Price"
      className="max-w-[12rem]"
    />
  );
}

API Reference

Generated from the component's exported types.

NumberInputProps

Prop	Type	Default	Description
`value`	`number \| null`	—	Controlled value. Pair with `onValueChange`. Use `null` for empty.
`defaultValue`	`number \| null`	`null`	Initial value for uncontrolled usage.
`onValueChange`	`(value: number \| null) => void`	—	Called with the new value (or `null` when cleared) on every change.
`min`	`number`	—	Minimum allowed value. The decrement stepper disables at this bound.
`max`	`number`	—	Maximum allowed value. The increment stepper disables at this bound.
`step`	`number`	`1`	Increment for steppers and Arrow keys. Defaults to `1`.
`largeStep`	`number`	—	Larger increment for PageUp / PageDown. Defaults to `step * 10`.
`precision`	`number`	—	Number of decimal places to round and display the committed value to.
`format`	`(value: number) => string`	—	Custom formatter for the displayed value when not focused.
`disabled`	`boolean`	`false`	Disables the input and both steppers.
`invalid`	`boolean`	`false`	Marks the field as invalid (forwarded to the underlying Input).
`placeholder`	`string`	—	Placeholder shown when the field is empty.
`className`	`string`	—	Extra classes for the wrapper element.
`inputClassName`	`string`	—	Extra classes for the underlying input.
`aria-label`	`string`	—	Accessible name for the spinbutton when there is no visible label.
`aria-labelledby`	`string`	—	ID of an element labelling the spinbutton.
`aria-describedby`	`string`	—	ID of an element describing the spinbutton.
`id`	`string`	—	Native id for the input.
`name`	`string`	—	Native name for the input (form submission).
`onBlur`	`(event: FocusEvent<HTMLInputElement>) => void`	—	Called when the input loses focus.