Money input
ProA field for an amount of money: a cap, a budget, a limit. The currency's symbol, its side and the decimal separator come from the locale through Intl ("$25.00", "25,00 €"), never a fixed "
null, never 0: nothing is filled in.It is a Field, with the label, hint above the field and the app's error. What the person types is read in the locale (the separator, grouping as the locale writes it or in threes, digits in any script). Text that isn't an amount, has more decimals than the currency has, or is below zero (unless allowNegative), gives null and, once the person leaves the field, an error that says how to write it; it takes the place of the app's error until it is fixed. suffix ("a month") follows the field and is read with it. note is the app's own line under the field, such as what happens at the amount ("I stop and ask before passing it"), also read with it.
With meter, a small bar under the field draws the app's estimate against the amount entered, and says it in words: the room it leaves, or how far past it the estimate goes. The bar is drawn only for an amount above zero; the words are read with the field.
With locked, the amount can't be changed and says why: the field stays focusable and readable, is read-only and aria-disabled, and is described by the reason, as Locked does.
Preview
Loading the preview
Install
First time? Get started sets up the registry and theme. Or with shadcn directly: npx shadcn@latest add @candor/money-input
Brings in: bidi, field, input, input-group, locale, locked, ops, tokens, utils
Usage
"use client"
import * as React from "react"
import { MoneyInput } from "@/components/candor/money-input"
export default function Example() {
const [cap, setCap] = React.useState<number | null>(25)
return (
<div className="flex max-w-sm flex-col gap-6">
<MoneyInput
label="Monthly budget"
value={cap}
onValueChange={setCap}
suffix="a month"
hint="My estimate is about $20, so $22 or more leaves room."
note="I stop and ask before passing it."
meter={{ estimate: 20, label: "My estimate" }}
/>
</div>
)
}<MoneyInput>
| Prop | Type | Default | Description |
|---|---|---|---|
| labelrequired | string | — | What the amount is, above the field: "Monthly budget". |
| value | number | null | undefined | — | The amount, when you control it. `null` is empty. |
| defaultValue | number | undefined | — | The amount at first, when you don't control it. Left out, the field is empty. |
| onValueChange | ((value: number | null) => void) | undefined | — | Called with the amount as the person types, or `null` when the field is emptied or what is typed isn't an amount. |
| currency | string | undefined | "USD" | The ISO 4217 code the amount is in, e.g. `"EUR"`. Defaults to `"USD"`. |
| suffix | string | undefined | — | What the amount is per, after the field and read with it: "a month". |
| hint | string | undefined | — | Help above the field that stays: "My estimate is about $20, so $22 leaves room". Read with the field. |
| note | string | undefined | — | The app's own line under the field, such as what happens at the amount: "I stop and ask before passing it". Read with the field. |
| error | string | null | undefined | — | What is wrong with the amount, in your words, from your validation. The field's own error for text that isn't an amount takes its place until fixed. |
| required | boolean | undefined | — | The amount must be given: marks the label and sets `aria-required`. |
| optional | boolean | undefined | — | Says "(optional)" after the label. |
| attempt | number | undefined | — | How many times the form has been submitted, as `Field` takes it: the first field with an error takes focus. |
| meter | MoneyInputMeter | undefined | — | Draws your estimate against the amount entered, with the room left or how far past it. |
| allowNegative | boolean | undefined | false | Takes amounts below zero (a refund, a credit). Left out, "-5" is refused with the field's error. |
| locked | string | null | undefined | — | Why the amount can't be changed right now. The field stays focusable and readable, can't be typed in, and says why. |
| name | string | undefined | — | The form field's name. The form gets the amount in plain digits ("25.5"), or "" when empty. |
| id | string | undefined | — | The field's id, for a `form-error-summary` link to point at. |
| className | string | undefined | — | Classes for the outer box. |
Strings
The fixed words, in English by default. Change any of them under moneyInput in <LocaleProvider strings={{ … }}>; the table is exported as moneyInputStrings.
| Key | English |
|---|---|
| notAnAmount | Enter an amount, like {example}. |
| tooManyDecimals | { one: "Use at most {count} decimal place, like {example}.", other: "Use at most {count} decimal places, like {example}." } |
| wholeOnly | Enter a whole amount, like {example}. |
| negative | Enter an amount of zero or more. |
| estimate | Estimate |
| meterEstimate | {label}: {estimate} |
| meterRoom | {label}: {estimate}, which leaves {left} |
| meterOver | {label}: {estimate}, which is {over} more than this |
Types
- MoneyInputMeter
- The meter's estimate: the app's figure in the same currency, and its label.
{ /** Your own estimate of what will be spent, in the field's currency. Drawn and said as an estimate; nothing is worked out from it. */ estimate: number; /** Words for the estimate ("My estimate"). Defaults to the `moneyInput.estimate` string, "Estimate". */ label?: string | undefined; }