# Amount Field

> A money input that formats as you type without moving the caret. Grouping, decimal mark and symbol side follow the locale; decimals stop where the currency does (none for yen). Type 2k or 1.5m, paste "$1,234.56" or "1.234,56 €", nudge with arrow keys, switch currency or pick a preset or Max. Reports minor units for payment APIs and flags amounts out of range.

- Slug: `amount-field`
- Category: [Inputs](https://www.assembli.design/category/inputs.md)
- Type: component
- Tags: currency, money, amount, price, payments, intl, number-input
- npm dependencies: lucide-react
- shadcn/ui dependencies: none
- Live preview: https://www.assembli.design/preview/amount-field
- Page: https://www.assembli.design/components/amount-field

![Amount Field preview](https://www.assembli.design/thumbnails/amount-field-light.png)

## Props

Other props pass through to the root element.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `value` | `number \| null` |  | The amount in major units (dollars, not cents). `null` when empty. |
| `defaultValue` | `number \| null` | `null` |  |
| `onValueChange` | `(value: number \| null, details: { minor: number \| null; currency: string }) => …` |  | Gets the amount and the same amount in minor units (cents), ready to send to a payments API. |
| `currency` | `string` | `"USD"` | ISO 4217 code. Decides the symbol, its side and the number of decimals (2 for USD, 0 for JPY). |
| `currencies` | `string[]` |  | Codes to offer in a switcher at the end of the field. |
| `onCurrencyChange` | `(currency: string) => void` |  |  |
| `locale` | `string` |  | Formatting locale, e.g. `de-DE` for "1.234,50 €". Defaults to `en-US`. |
| `min` | `number` |  |  |
| `max` | `number` |  |  |
| `step` | `number` | `1` | Arrow keys add or take this much; Shift moves ten times as far. Defaults to 1. |
| `presets` | `number[]` |  | Quick amounts shown as chips under the field. |
| `maxButton` | `boolean` |  | Adds a Max button that fills in `max`, for transfers and withdrawals. |
| `label` | `React.ReactNode` |  |  |
| `hint` | `React.ReactNode` |  | Quiet text to the right of the label, such as "Balance $1,240.00". |
| `description` | `React.ReactNode` |  |  |
| `error` | `React.ReactNode` |  | Replaces the description and the built-in range messages. |
| `size` | `"md" \| "lg"` | `"md"` |  |
| `inputClassName` | `string` |  | Classes for the input element itself; `className` goes on the root. |

## Install

One-time setup (needs a subscription):

1. Add the registry to the project's `components.json`: `{"@assembli":{"url":"https://www.assembli.design/r/{name}.json","headers":{"Authorization":"Bearer ${ASSEMBLI_API_KEY}"}}}` (merge into `"registries"`).
2. Put an API key from https://www.assembli.design/account in `.env.local` as `ASSEMBLI_API_KEY=asm_…`.

Then install with the shadcn CLI (writes `components/amount-field/amount-field.tsx` and installs dependencies):

```bash
npx shadcn@latest add @assembli/amount-field
```

Registry item JSON: https://www.assembli.design/r/amount-field.json (send `Authorization: Bearer <api key>`)

## Code

> Component source needs an Assembli subscription ($12/month or $96/year) and an API key sent as `Authorization: Bearer <key>`. To get one without copying anything, POST https://www.assembli.design/api/agent/login (or call the MCP tool connect_account), show the user the link it returns, and poll https://www.assembli.design/api/agent/token for the key. Or subscribe at https://www.assembli.design/pricing and create a key at https://www.assembli.design/account.