Money field

When to use #

Use it for

Payments, budgets and invoices where the amount and currency go together.
You want min and max limits with clear feedback.

Skip it when

The value is a plain number; use a number field.
The currency is fixed and invisible; use a number input with a suffix.

Installation #

terminal

pnpm dlx shadcn@latest add https://caliperui.site/r/money-field.json

Adds its 5 files to components/ui/, each with its own stylesheet, and installs their packages. No account needed. The first part also adds Caliper UI’s tokens; import them once as in Installation.

Usage #

This is the code behind the preview above.

example.tsx

import { useState } from "react"
import { MoneyField } from "@/components/ui/money-field"

export function PaymentAmount() {
  const [cents, setCents] = useState<number | null>(2500);
  return (
    <div className="w-full max-w-xs">
      <MoneyField label="Amount" value={cents} onValueChange={setCents} max={100000} quickAdd={[10, 20]} description="Up to 1,000 per payment." />
    </div>
  );
}

API reference #

MoneyField

component

PropTypeDefault

label *string—

valuenumber | null—

defaultValuenumber | nullnull

currency"USD" | "EUR" | "GBP" | "JPY"—

defaultCurrency"USD" | "EUR" | "GBP" | "JPY""USD"

currenciesreadonly ("USD" | "EUR" | "GBP" | "JPY")[]["USD", "EUR", "GBP", "JPY"]

minnumber—

maxnumber—

quickAddreadonly number[][10, 50]

disabledboolean—

namestring—

idstring—

descriptionstring—

onValueChange((value: number | null, details: MoneyDetails) => void)—

onCurrencyChange((currency: "USD" | "EUR" | "GBP" | "JPY") => void)—

classNamestring—

It exposes spinbutton and status semantics, with aria-label, aria-hidden, aria-valuenow, aria-valuemin, aria-valuemax and aria-valuetext kept in step with state. Changes that matter are announced through a live region.

KeyBehaviour

↑Moves to the previous item or value.

PageUpMoves by a larger step, or to the previous page.

↓Moves to the next item or value.

PageDownMoves by a larger step, or to the next page.

Motion #

It declares no animation in its component source. Any transition comes from its stylesheet, which uses the duration tokens that collapse to instant under prefers-reduced-motion.