Chinese Amount Input (React)

Checks, receipts, contracts and quotations all need the amount written out in formal Chinese uppercase numerals. This component pairs a numeric input (inputMode="decimal", digits and a single decimal point only, at most two decimals, thousands separators inserted as you type) with a mirror row underneath: every keystroke updates 「新臺幣壹萬貳仟元伍角整」 character by character — only the characters that changed animate, while the prefix and higher digits stay put — and a copy button on the right copies the full string and flashes a check on success. The conversion rules live in a standalone pure function, toChineseUpper(): digits 零壹貳參肆伍陸柒捌玖, places 拾佰仟, groups 萬億兆, decimals 角分, consecutive zeros collapsed, trailing zeros in a group dropped, 「壹拾」 kept, supported up to 兆 (10^12).

Playground

Tune the props live — the code snippet updates as you go, so you can dial in the look you want before copying it.

<ChineseAmountInput />

Installation

npx shadcn@latest add https://webberui.com/r/chinese-amount-input.json

Usage

import {
  ChineseAmountInput,
  toChineseUpper,
} from "@/components/ui/chinese-amount-input";

<ChineseAmountInput
  label="報價總額（含稅）"
  prefix="新臺幣"
  onChange={(raw, { upper, formatted, amount }) => {
    console.log(raw); // "12000.5"
    console.log(formatted); // "12,000.5"
    console.log(upper); // "新臺幣壹萬貳仟元伍角整"
    console.log(amount); // 12000.5
  }}
/>

// The converter can be used on its own (e.g. when printing a check or generating a PDF)
toChineseUpper(120000.5); // "壹拾貳萬元伍角整"
toChineseUpper("100000001", { prefix: "人民幣" }); // "人民幣壹億零壹元整"
toChineseUpper("1,680.32"); // "壹仟陸佰捌拾元參角貳分" (thousands separators are stripped)

Props

ChineseAmountChangeDetail

toChineseUpper(amount, opts?)

toChineseUpper(amount: number | string, opts?: ToChineseUpperOptions): string — accepts a number or a string (strings may contain thousands separators and full-width digits). Returns "" for an empty or non-numeric input; throws a RangeError for negative amounts or when the integer part exceeds 16 digits (兆). Numbers are rounded to fen (two decimals); strings with more than two decimals are truncated, matching the input's behavior.

sanitizeAmount(raw, allowDecimal?) (cleans to a plain numeric string), formatAmount(raw) (adds thousands separators) and the constant MAX_AMOUNT_INT_DIGITS (16) are also named exports.

How it works

Conversion reference (without prefix):

• 「壹拾」 is never shortened to 「拾」 (12 → 壹拾貳): uppercase amounts exist to resist tampering, unlike the spoken 「十二」
• Jiao without fen is written 「元X角整」, fen without jiao 「元零X分」, and both 「元X角X分」
• The integer part supports up to 16 digits (just under 10,000 兆); beyond that the input shows an out-of-range error and sets aria-invalid. When max is set, exceeding it shows a similar message but does not block input, so the user can correct it themselves
• Full-width digits and the full-width period (a common slip under Chinese IMEs) are accepted and normalized to ASCII; thousands separators in pasted text are stripped and re-inserted for display
• The caret stays on the same digit after separators are inserted instead of jumping to the end

Accessibility

• The real input is a single native input (inputMode="decimal"), so mobile devices bring up the numeric keypad; aria-describedby points at both the uppercase mirror row and the hint message
• The mirror row is an aria-live="polite" region; the per-character animation is aria-hidden, so screen readers only hear the complete string (e.g. 「新臺幣壹萬貳仟元整」)
• aria-invalid is set when the amount is out of range or above max, and the error message lives in a role="status" region
• The copy button is type="button" with an aria-label (which switches to "copied" after success), keyboard operable with a focus-visible ring
• When the user has "reduce motion" enabled at the system level, the uppercase text is swapped in place with no per-character fade or slide, and the copy-icon and message transitions are disabled as well