Forms

Currency Input

Money field with a currency selector and live thousand/decimal formatting.

Import

tsx

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

bash

npx cooud-ui add currency-input

Examples

Multi-currency

A payments-grade money field. Digits accumulate from the right as minor units (typing 1 2 3 4 5 reads 0,01 → 12,34 → 123,45), grouping and decimals are live-formatted per the currency's locale, and `onValueChange` hands back integer cents plus formatting `meta`. Switch currencies from the fused selector.

Amount

BRL · 1,299.00 in major units

tsx

function CurrencyInputDemo() {
  const [cents, setCents] = useState<number | null>(129900);
  const [meta, setMeta] = useState<CurrencyInputMeta | null>(null);

  return (
    <div className="flex w-full max-w-xs flex-col gap-2">
      <FieldLabel htmlFor="amount">Amount</FieldLabel>
      <CurrencyInput
        id="amount"
        value={cents}
        onValueChange={(next, info) => {
          setCents(next);
          setMeta(info);
        }}
        aria-label="Amount"
      />
      <FieldDescription>
        {cents == null
          ? "Digits fill in from the right — try typing 5 0 0 0 0."
          : `${meta?.currency ?? "BRL"} · ${(cents / 100).toLocaleString("en-US", {
              minimumFractionDigits: 2,
            })} in major units`}
      </FieldDescription>
    </div>
  );
}

Single currency

Pass a one-entry `currencies` list to lock the field to a currency — the selector collapses into a static, non-interactive prefix.

tsx

<CurrencyInput
  currencies={[{ code: "BRL", symbol: "R$", locale: "pt-BR" }]}
  defaultValue={12900}
  aria-label="Price"
/>

Hard ceiling

`max` is a live upper clamp (in minor units) the amount can never be typed past, while `min` is enforced on blur so in-progress entries aren't fought mid-type.

Monthly budgetMáx R$ 5.000,00

A hard live ceiling — you can’t type past the limit.

tsx

function CurrencyLimitDemo() {
  // R$ 5.000,00 hard ceiling, expressed in minor units (cents).
  const MAX_CENTS = 500000;
  const [cents, setCents] = useState<number | null>(320000);

  return (
    <div className="flex w-full max-w-xs flex-col gap-2">
      <div className="flex items-center justify-between">
        <FieldLabel htmlFor="budget">Monthly budget</FieldLabel>
        <span className="text-xs text-fg-tertiary tabular-nums">Máx R$ 5.000,00</span>
      </div>
      <CurrencyInput
        id="budget"
        currencies={[{ code: "BRL", symbol: "R$", locale: "pt-BR" }]}
        value={cents}
        onValueChange={setCents}
        max={MAX_CENTS}
        aria-label="Monthly budget"
      />
      <FieldDescription>A hard live ceiling — you can’t type past the limit.</FieldDescription>
    </div>
  );
}

API Reference

Generated from the component's exported types.

CurrencyInputProps

Prop	Type	Default	Description
`value`	`number \| null`	—	Controlled amount in minor units (integer cents). Use `null` for empty. Pair with `onValueChange`.
`defaultValue`	`number \| null`	`null`	Initial amount in minor units for uncontrolled usage. Defaults to `null` (empty).
`onValueChange`	`(value: number \| null, meta: CurrencyInputMeta) => void`	—	Fired on every edit with the amount in minor units (`null` when cleared) plus formatting `meta`.
`currencies`	`CurrencyOption[]`	—	Selectable currencies. Defaults to BRL, USD and EUR. A single entry renders a static (non-interactive) prefix.
`currency`	`string`	—	Controlled active currency code. Pair with `onCurrencyChange`.
`defaultCurrency`	`string`	—	Initial active currency code for uncontrolled usage. Defaults to the first `currencies` entry.
`onCurrencyChange`	`(code: string, meta: CurrencyInputMeta) => void`	—	Fired when the user picks a different currency (also re-fires `onValueChange` with the new `meta`).
`min`	`number`	`0`	Lower clamp in minor units, enforced on blur. Defaults to `0` (no negatives).
`max`	`number`	—	Upper clamp in minor units — a hard live ceiling the value can never be typed past.
`invalid`	`boolean`	`false`	Marks the field invalid (red border + `aria-invalid`).
`disabled`	`boolean`	`false`	Disables the field and the currency selector.
`selectorLabel`	`string`	`"Select currency"`	Accessible name for the currency selector button.
`inputClassName`	`string`	—	Extra classes for the underlying `<input>`.