# Currency input

> A locale-aware money field with caret-safe typing, currency formatting, keyboard steps and clean numeric values for your backend.

Money fields often reformat on every keystroke, moving the caret and turning a simple amount into a fight. This input groups the digits the way the locale does as you type and puts the caret back after the same digit, so separators appear without the caret ever jumping; at rest the amount rolls into place when it changes. It understands currency fraction digits, including zero-decimal currencies, reports number or null instead of a formatted string, and adds min/max validation, keyboard stepping and a folding clear action to the shared Hairline field.

## Install

```bash
npx shadcn@latest add https://hairlineui.com/r/currency-input.json
```

Needs React 19, Tailwind CSS v4 and shadcn/ui theme variables (any style, light and dark). Icons from lucide-react.

- npm: none
- Hairline UI components it needs (the CLI installs them too): `number-roll`, `text-morph`
- Docs and live preview: https://hairlineui.com/ui/currency-input
- Registry item (source): https://hairlineui.com/r/currency-input.json

## Usage

```tsx
import { CurrencyInput } from "@/components/currency-input";

<CurrencyInput
  label="Monthly price"
  value={price}
  onValueChange={setPrice}
  currency="USD"
  locale="en-US"
  min={0}
  step={5}
  clearable
/>
```

## A plan price with an annual total

The callback receives a number, so calculations and requests do not need to strip symbols or parse formatted text again.

```tsx
"use client";

import * as React from "react";
import { CurrencyInput } from "@/components/currency-input";

export function PlanPrice() {
  const [monthly, setMonthly] = React.useState<number | null>(24);
  const annual = monthly === null ? 0 : monthly * 12;

  return (
    <div>
      <CurrencyInput
        label="Monthly price"
        name="monthlyPrice"
        value={monthly}
        onValueChange={setMonthly}
        currency="EUR"
        locale="de-DE"
        min={0}
        step={1}
      />
      <output>Annual total: {annual.toFixed(2)} EUR</output>
    </div>
  );
}
```

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `value / defaultValue` | `number \| null` | – | The numeric amount; null means empty. |
| `onValueChange` | `(value: number \| null) => void` | – | Reports valid edits, steps and clearing. |
| `onValueCommit` | `(value: number \| null) => void` | – | Runs when a draft, keyboard step or clear settles. |
| `locale / currency` | `string / string` | `"en-US" / "USD"` | Intl locale and ISO currency code. |
| `min / max / step` | `number` | `-Infinity / Infinity / 1` | Allowed range and Arrow Up/Down increment. |
| `name` | `string` | – | Submits the unformatted number through a hidden input. |
| `clearable` | `boolean` | `false` | Adds a folding clear button when there is content. |
| `size` | `"sm" \| "md"` | `"md"` | 28px or 36px field height. |
| `label / hint / error / placeholder` | `ReactNode / ReactNode / ReactNode / string` | – | Shared field copy and external validation. |
| `required / disabled / id / className` | `boolean / boolean / string / string` | – | Standard form and layout attributes. |

## States

- **rest**: The amount carries locale grouping and the currency’s decimal places; a new value rolls its digits into place the way it moved.
- **editing**: Separators appear as you type and the caret stays after the digit it was on; the symbol and field stay fixed.
- **step**: Arrow keys adjust the amount by step, Shift by ten steps, and keep the caret at the end.
- **invalid**: An unreadable or out-of-range amount shakes once and explains what can be entered.
- **clear**: The clear icon folds into the field, empties both the visible and submitted values, and keeps focus.

## What it handles

Currency editing needs locale separators, stable caret behaviour, currency precision and numeric output. Formatting alone does not solve those; the editing state has to be separate from the stored value.

- **Grouping as you type**: Separators appear while you type and the caret stays after the same digit, in any locale’s grouping and decimal mark.
- **Locale and currency**: Intl supplies grouping, decimal separators, symbol position and the currency’s own fraction digits.
- **Numeric integration**: Callbacks and hidden form values carry number or null, never currency symbols or grouped text.
- **Validation with recovery**: Unreadable and out-of-range drafts stay in the field with a precise error; Escape restores the settled value.
- **Keyboard stepping**: Arrow Up and Down move by step (Shift for ten steps) with decimal-safe rounding and a small bump at the limit.
- **Responsive field states**: Currency symbols morph when the currency changes, Clear folds its own width open, and errors replace the hint.

## Replaces

native <input type="number">, react-number-format, manual Intl.NumberFormat wiring, locale separator parsing, currency fraction-digit helpers

## Where it fits

- **Pricing and plans**: Enter a monthly or annual price with live totals.
- **Invoices**: Type line-item amounts in the customer’s currency and locale.
- **Commerce settings**: Set product prices, discounts and shipping thresholds.
- **Finance forms**: Collect budgets, expenses and transfer amounts as clean numbers.

## Notes

- The default en-US locale is intentional for deterministic server rendering; pass the visitor’s locale when it is known.
- The input uses inputMode="decimal" and a text draft rather than the browser’s number control. At rest a NumberRoll draws the amount over the field; screen readers read the field itself.
- Values are rounded to the currency’s fraction digits on blur or Enter. Arrow stepping also respects decimal step precision.
- Reduced motion removes the clear-button width transition, the limit bump and the digit roll.

License: MIT (https://hairlineui.com/license#components)
