Skip to main content
Version: Next 🚧

AmountField

AmountField is a React Native money input: the currency's symbol, then the amount, grouped as the user types, such as $1,234.50. It takes as many decimal places as the currency has, two for the dollar and none for the yen, and the value is a number, such as 1234.5, or null when empty.

It comes as a form field or as a large amount, big and centered like a send-money screen. A currency button can open a CurrencyPicker, and the field follows the iOS, Material or web design. No masking library and no dependency.

import { AmountField } from '@elik56a/react-native-pickers';
Loading…
<AmountField label="Price" value={amount} onChange={setAmount} />

Type 1234.5: the field shows 1,234.5 as you type, and 1,234.50 once you leave it. Paste $1,234.56 and the amount is read from it.

Try the props​

Platform
variant
locale
error
<AmountField
  label="Amount"
  value={amount}
  onChange={setAmount}
  locale="en-US"
/>

The currency​

currency sets the symbol and the decimal places, and defaultCurrency starts with one, 'USD' by default. showCurrencyPicker adds a button with the flag and code that opens the currency list, which takes the CurrencyPicker props for which currencies it offers.

Loading…
<AmountField
  label="Budget"
  showCurrencyPicker
  preferred={['USD', 'EUR', 'GBP']}
  currency={currency}
  onCurrencyChange={setCurrency}
  value={amount}
  onChange={setAmount}
/>

Picking a currency with fewer decimal places drops the extra digits: 12.50 in dollars becomes 12 in yen.

A large amount​

variant="large" shows the amount big and centered, with the currency as a pill under it, for checkout, tip and send-money screens. The amount shrinks as it grows so it stays on one line. Its weight follows the design: bold as in Apple Cash on iOS, regular as in Google Pay in Material.

Loading…
<AmountField
  variant="large"
  label="Send to Maya"
  showCurrencyPicker
  currency={currency}
  onCurrencyChange={setCurrency}
  value={amount}
  onChange={setAmount}
  helperText="Arrives today"
/>

Tap the amount to type. The text input is hidden under it, so the keyboard, paste and screen readers work as in any field.

Number formats​

locale sets the separators and the symbol's side: $1,234.50 in English, 1.234,50 € in German and ₹12,34,567 with Indian grouping (en-IN). It's the device locale by default. Digits are always Latin, so what the user types reads back the same.

Loading…
<AmountField label="Betrag" locale="de-DE" defaultCurrency="EUR" value={amount} onChange={setAmount} />

While typing, anything but digits and the locale's decimal separator is dropped, as are digits past the currency's decimal places, so 12.345 can't be typed in dollars. Amounts are positive and up to 15 digits before the decimal point, as many as a JavaScript number holds exactly.

Errors and helper text​

error shows the field as invalid: a red border and label, and the message under the field when it's a string. helperText is the line under the field while there's no error message, and required adds an asterisk to the label. The field doesn't check the amount: set error from your form.

Loading…
<AmountField
  label="Withdraw"
  required
  helperText={`Balance: $${BALANCE}`}
  error={amount !== null && amount > BALANCE && 'More than your balance'}
  value={amount}
  onChange={setAmount}
/>

Storing the amount​

onChange gets the amount in the currency's main unit, such as 12.5 for twelve dollars fifty. Payment APIs such as Stripe take the minor unit, cents, as a whole number. Convert with the currency's decimals:

import { getCurrency } from '@elik56a/react-native-pickers';
import type { CurrencyCode } from '@elik56a/react-native-pickers';

const toMinorUnits = (amount: number, currency: CurrencyCode) => Math.round(amount * 10 ** getCurrency(currency)!.decimals);

toMinorUnits(12.5, 'USD'); // 1250
toMinorUnits(1200, 'JPY'); // 1200

Props​

PropTypeDefaultDescription
valuenumber | null—The amount, null when empty. Leave it out to keep the amount inside.
defaultValuenumber | nullnullStarting amount when value isn't set.
onChange(value: number | null) => void—Called as the user types or picks a currency that drops decimal places.
currencyCurrencyCode—The currency: its symbol, decimal places and flag.
defaultCurrencyCurrencyCode'USD'Starting currency when currency isn't set.
onCurrencyChange(currency: CurrencyCode) => void—Called when the user picks a currency.
variant'field' | 'large''field'A form field, or a large centered amount. See A large amount.
showCurrencyPickerbooleanfalseA button with the currency's flag and code that opens a searchable currency list.
localestringdevice localeSeparators, the symbol's side and the currency names.
labelstring—Above the field, on its border in Material, or over a large amount. Screen readers hear Amount without one.
placeholderstringzero in the currency's format, e.g. 0.00Shown while empty.
disabledbooleanfalse
autoFocusbooleanfalseFocus the input on mount.
errorstring | boolean—Shows the field as invalid, with the message under it when it's a string. See Errors and helper text.
helperTextstring—Shown under the field, replaced by the error message.
requiredbooleanfalseAdds an asterisk to the label and tells screen readers the field is required. The amount isn't checked.
currencies / exclude / preferredCurrencyCode[]—Which currencies the list offers, and which come first. See CurrencyPicker.
showFlagbooleantrueFlags in the currency list.
preferredLabel / allCurrenciesLabelstring'Suggested' / 'All currencies'Headers of the list.
presentation'auto' | 'dropdown' | 'bottomSheet' | 'modal' | 'inline''auto'Where the currency list opens: a dropdown on the web, a bottom sheet on native.
currencySheetTitlestring'Currency'Title of the currency sheet.
sheetPartial<SheetChromeProps>sheetProps.height: 0.8Options for the currency sheet, as CurrencyPicker's.
theme / designSee Theming and Designs.
styleStyleProp<ViewStyle>—The field's container.
styles{ label, field, input, symbol, amount, caret, currencyButton, currencyCode, chevron, helperText }—Slot styles. field and input style the form field, amount and caret the large amount.
testIDstring—On the text input; the currency button gets ${testID}-currency.

Accessibility​

The input is named by the label and the currency, such as "Price, US Dollar", or "Amount" without a label. The keyboard is the number pad, with a decimal key for currencies that have decimal places. The currency button reads "Currency: " with the currency's name, with an expanded state while the list is open. Like every field, it reads "required" when required is set and the error message as its hint.

Related​