# Currency Input

Large amount entry with a built-in number keypad and currency badge. Digits appear in place as you type, and an amount over the available balance turns red straight away.

> Composed · Pro · Forms & Inputs — React Native, Expo Go compatible.

## Install

```bash
npx @lumioui/cli add pro/currency-input
```

## Import

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

## Variants

- `exchange` — Exchange: `npx @lumioui/cli add pro/currency-input-exchange`
- `send` — Send: `npx @lumioui/cli add pro/currency-input-send`

## Props

| Prop | Type | Notes |
| --- | --- | --- |
| `value?` | `string` | Controlled amount as a decimal string ("", "12", "12.5"). |
| `defaultValue?` | `string` | Uncontrolled initial amount. Default "". |
| `onValueChange?` | `(value: string) => void` | Fires with the next string after every accepted key. |
| `currency?` | `string` | Controlled currency code. |
| `defaultCurrency?` | `string` | Uncontrolled initial currency code. Default the first of `currencies`. |
| `onCurrencyChange?` | `(code: string) => void` | Fires when the pill switches currency. |
| `currencies?` | `CurrencyOption[]` | Currencies the pill can switch between. A single entry hides the chevron. |
| `onCurrencyPress?` | `() => void` | Replace the built-in cycle — open your own picker sheet from here. |
| `maxValue?` | `number` | Hard cap — keys that would pass it are refused with a shake. |
| `limit?` | `number` | Soft cap — typing past it is allowed, but the figure turns destructive  and shakes once (e.g. more than the available balance). |
| `limitMessage?` | `string` | Message shown in place of the caption while over `limit` or when `error` is a string. |
| `error?` | `boolean | string` | External error — `true` tints the figure, a string also replaces the caption. |
| `caption?` | `React.ReactNode` | Muted line under the figure — balance, conversion, fees. |
| `children?` | `React.ReactNode` | Slot between the figure and the keypad — quick-amount chips, a note field. |
| `keypad?` | `boolean` | Render the built-in keypad. false = display only (drive `value` yourself). Default true. |
| `keypadVariant?` | `"plain" | "filled"` | Keypad look. Default "plain". |
| `entry?` | `"decimal" | "cents"` | "decimal" types left to right; "cents" shifts in from the right. Default "decimal". |
| `size?` | `"md" | "lg"` | Figure size: md 40pt, lg 56pt base before shrink-to-fit. Default "lg". |
| `disabled?` | `boolean` | Disables the keypad and pill. |
| `sheen?` | `number` | Change (e.g. increment) when the amount is committed — one Sheen crosses the figure. |
| `className?` | `string` | — |

## Icons rendered

- `chevron-down` — /icons.html?i=chevron-down

Source: https://lumioui.com/components/currency-input