Skip to content
Tier

Money input

Pro

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 "

quot;; 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.

Markdown

Preview

Loading the preview

Install

With the Candor CLI

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

TSX · The example above
"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>

PropTypeDefaultDescription
labelrequiredstring—What the amount is, above the field: "Monthly budget".
valuenumber | null | undefined—The amount, when you control it. `null` is empty.
defaultValuenumber | 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.
currencystring | undefined"USD"The ISO 4217 code the amount is in, e.g. `"EUR"`. Defaults to `"USD"`.
suffixstring | undefined—What the amount is per, after the field and read with it: "a month".
hintstring | undefined—Help above the field that stays: "My estimate is about $20, so $22 leaves room". Read with the field.
notestring | 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.
errorstring | 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.
requiredboolean | undefined—The amount must be given: marks the label and sets `aria-required`.
optionalboolean | undefined—Says "(optional)" after the label.
attemptnumber | undefined—How many times the form has been submitted, as `Field` takes it: the first field with an error takes focus.
meterMoneyInputMeter | undefined—Draws your estimate against the amount entered, with the room left or how far past it.
allowNegativeboolean | undefinedfalseTakes amounts below zero (a refund, a credit). Left out, "-5" is refused with the field's error.
lockedstring | 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.
namestring | undefined—The form field's name. The form gets the amount in plain digits ("25.5"), or "" when empty.
idstring | undefined—The field's id, for a `form-error-summary` link to point at.
classNamestring | 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.

KeyEnglish
notAnAmountEnter an amount, like {example}.
tooManyDecimals{ one: "Use at most {count} decimal place, like {example}.", other: "Use at most {count} decimal places, like {example}." }
wholeOnlyEnter a whole amount, like {example}.
negativeEnter an amount of zero or more.
estimateEstimate
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; }