# Number Input

A strict numeric input component with formatting, prefixes, and steppers.

> For the complete documentation index, see [llms.txt](/llms.txt). Markdown variants are available by appending `.md` to any URL or sending an `Accept: text/markdown` header. An agent skill is available at [/.well-known/agent-skills/site-skill.md](/.well-known/agent-skills/site-skill.md).



A specialized input primitive for strictly handling numeric data, featuring automatic formatting on blur, up/down steppers, and support for prefixes/suffixes.



## Demo [#demo]

<ComponentPreview name="number-input-demo">
  <div className="flex flex-col gap-8 py-8 items-center w-full mx-auto">
    <div className="grid w-64 items-center gap-1.5">
      <Label htmlFor="quantity">
        Quantity (Number Only)
      </Label>

      <NumberInput id="quantity" defaultValue="1" min="1" />
    </div>

    <div className="grid w-64 items-center gap-1.5">
      <Label htmlFor="currency">
        Currency (USD)
      </Label>

      <NumberInput id="currency" prefix="$" defaultValue="1250" formatOptions="{ minimumFractionDigits: 2 }" />
    </div>

    <div className="grid w-64 items-center gap-1.5">
      <Label htmlFor="weight">
        Weight (kg)
      </Label>

      <NumberInput id="weight" suffix="kg" defaultValue="15.5" step="0.5" />
    </div>

    <div className="grid w-64 items-center gap-1.5">
      <Label htmlFor="percentage">
        Discount (%)
      </Label>

      <NumberInput id="percentage" suffix="%" defaultValue="15" min="0" max="100" />
    </div>
  </div>
</ComponentPreview>

## Usage [#usage]

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

export function MyComponent() {
  return (
    <NumberInput 
      prefix="$"
      defaultValue={1250}
      formatOptions={{ minimumFractionDigits: 2 }} 
    />
  );
}
```

## API Reference [#api-reference]

| Prop            | Type                                   | Description                                     |
| --------------- | -------------------------------------- | ----------------------------------------------- |
| `value`         | `number`                               | The controlled value of the input.              |
| `defaultValue`  | `number`                               | The uncontrolled default value.                 |
| `onChange`      | `(value: number \| undefined) => void` | Callback when the valid parsed number changes.  |
| `min`           | `number`                               | Minimum allowed value.                          |
| `max`           | `number`                               | Maximum allowed value.                          |
| `step`          | `number`                               | Step increment for the arrows. Defaults to `1`. |
| `prefix`        | `React.ReactNode`                      | Element to render on the left side.             |
| `suffix`        | `React.ReactNode`                      | Element to render on the right side.            |
| `formatOptions` | `Intl.NumberFormatOptions`             | Formatting options for `Intl.NumberFormat`.     |