# Money input

A 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 "$"; the amount is shown to the currency's decimals once the person leaves the field, in tabular digits. Empty is `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.

- Registry name: `money-input` (`@candor/money-input`)
- Tier: Pro. Installing it needs a Pro, Premium or Team licence key: the person runs `npx candor-ui key <key>` themselves; never ask for the key in chat or write it to a file.
- Docs: https://candor.themethodic.com/docs/money-input

## Install

```bash
npx candor-ui@4 add money-input
```

Run `npx candor-ui@latest init` once first (https://candor.themethodic.com/get-started.md). Without the CLI: `npx shadcn@latest add @candor/money-input`.
It brings in: bidi, field, input, input-group, locale, locked, ops, tokens, utils.

## Example

```tsx
"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>

Props:

- `label: 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` (default `"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` (default `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 (`moneyInput`)

The fixed words, English by default. Override any of them under `moneyInput` in `<LocaleProvider strings={{ moneyInput: { … } }}>`; the table is exported as `moneyInputStrings`.

- `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.

```ts
{
  /** 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;
}
```

## Rules for using Candor UI

- Components take plain typed data. Never pass model output as HTML or render it as a link; messages are typed blocks.
- A control that can't be used says why: wrap it in `<Locked reason="…">`, don't just disable it.
- Don't show a value you don't have: leave it out (it renders as —) rather than guess. An estimate is labelled as one.
- Nothing is pre-selected in a decision a person makes, and the agent is named from your app's data, never from model output.
- Your app's words go in `LocaleProvider`: its fixed strings in `strings`, its nouns in `nouns`; entity kinds and agent roles in `EntityKindsProvider` and `AgentRolesProvider`.
