arkyn

v3.0.1-beta.72

CurrencyInput

The CurrencyInput component is a specialized input field for monetary values that applies automatic formatting based on the currency's locale. It supports over 20 different currencies and offers real-time formatting as the user types.

tsx

import { CurrencyInput } from "@arkyn/components";

Basic usage

Basic usage of an input requires a name and locale property.

tsx

<CurrencyInput name="price" locale="USD" />

Currency

You can set the currency using the locale property, which is mandatory. The value formatting will be applied automatically as the user types, following the standards of the specified currency. You can also set a maximum value using the max property.

Locale

The locale property is mandatory and defines the currency locale for formatting. Common examples include USD (US Dollar), EUR (Euro), and BRL (Brazilian Real).

tsx

<CurrencyInput
  name="price-brl"
  locale="BRL"
  placeholder="Enter the value"
  leftIcon={TrendingUp}
/>

Max value

The max property allows you to set a maximum value that the user can enter. If the entered value exceeds this limit, it will not be reflected in the input.

tsx

<CurrencyInput
  name="price-max"
  locale="USD"
  max={5000}
  label="Maximum: $5,000.00"
  leftIcon={Building}
/>

Supported currencies

The component supports over 20 different currency localizations:
  • USD - US Dollar
  • EUR - Euro
  • BRL - Brazilian Real
  • GBP - British Pound
  • JPY - Japanese Yen
  • CAD - Canadian Dollar
  • AUD - Australian Dollar
  • CHF - Swiss Franc
  • CNY - Chinese Yuan
  • SEK - Swedish Krona
  • NZD - New Zealand Dollar
  • INR - Indian Rupee
  • RUB - Russian Ruble
  • ZAR - South African Rand
  • MXN - Mexican Peso
  • SGD - Singapore Dollar
  • HKD - Hong Kong Dollar
  • NOK - Norwegian Krone
  • KRW - South Korean Won
  • TRY - Turkish Lira
  • IDR - Indonesian Rupiah
  • THB - Thai Baht

Sizes

The available sizes are md and lg, following the same pattern as the other input components.

tsx

<CurrencyInput
  name="price-md"
  locale="USD"
  placeholder="Enter the amount"
  size="md"
/>
<CurrencyInput
  name="price-lg"
  locale="USD"
  placeholder="Enter the amount"
  size="lg"
/>

Variants

The available variants are solid, outline, and underline, providing different visual styles.

tsx

<CurrencyInput
  name="amount-solid"
  locale="BRL"
  placeholder="R$ 0.00"
  variant="solid"
/>
<CurrencyInput
  name="amount-outline"
  locale="BRL"
  placeholder="R$ 0.00"
  variant="outline"
/>
<CurrencyInput
  name="amount-underline"
  locale="BRL"
  placeholder="R$ 0.00"
  variant="underline"
/>

Prefix and suffix

Use prefix and suffix to add text or fixed icons at the beginning or end of the input.

With prefix

tsx

<CurrencyInput
  name="monthly-cost"
  label="Custo Mensal"
  locale="BRL"
  prefix="R$"
  placeholder="0,00"
  leftIcon={Calculator}
/>

With suffix

tsx

<CurrencyInput
  name="annual-fee"
  label="Taxa Anual"
  locale="USD"
  prefix="$"
  suffix="USD"
  placeholder="0.00"
  leftIcon={Receipt}
/>

Input states

The component supports different states, such as disabled, read-only, and loading.

Disabled input

The disabled state prevents any user interaction with the field and prevents data from being submitted through a form.

tsx

<CurrencyInput
  name="disabled-with-value"
  label="Disabled amount"
  locale="USD"
  value={1000}
  disabled
  leftIcon={Banknote}
/>

Read-only input

The read-only state allows the user to view the field value but cannot edit it. Unlike the disabled state, the value can be selected and copied, and field data can be submitted via a form.

tsx

<CurrencyInput
  name="readonly-total"
  label="Calculated total"
  locale="BRL"
  value={15750.8}
  readOnly
  leftIcon={Calculator}
/>

Loading state

The loading state displays a spinner and automatically disables input. The spinner appears on the left by default, or on the right if there is a rightIcon.

tsx

<CurrencyInput
  name="loading-right"
  label="Processing payment..."
  locale="USD"
  placeholder="$0.00"
  rightIcon={CreditCard}
  isLoading
/>

Validation and errors

The component integrates with form validation systems and can display error messages. If an error message is provided via the errorMessage property, it will take precedence over messages from the form provider.
Customizable Forms
For forms, it is recommended to use the FormProvider which offers native integration with all form tools.

tsx

<CurrencyInput
  name="invalid-salary"
  label="Wage"
  locale="BRL"
  placeholder="R$ 0,00"
  errorMessage="Valor deve ser maior que R$ 1.000,00"
  leftIcon={DollarSign}
  showAsterisk
/>

onChange callback

The onChange callback differs from HTML's onChange; it provides three parameters for maximum flexibility:

tsx

function handleCurrencyChange(
  event: ChangeEvent<HTMLInputElement>,
  originalValue: string,
  maskedValue: string
) {
  // event - original event
  // originalValue - unformatted numeric value
  // maskedValue - formatted value with currency mask


  console.log("Original value:", originalValue); // "1500.50"
  console.log("Formatted value:", maskedValue); // "R$ 1,500.50"


  // Use originalValue for calculations
  const numericValue = Number(originalValue);


  // Use maskedValue for display
  setDisplayValue(maskedValue);
}

Properties

name - string (required) Name of the field for form manipulation
locale - Locale (required) Currency locale for formatting (e.g., "USD", "EUR", "BRL", etc.)
label - string Label text to display above the input
errorMessage - string Error message to display below the input
isLoading - boolean (default: false) Controls the loading state with a spinner
size - "md" | "lg" (default: "md") Input size
variant - "solid" | "outline" | "underline" (default:"solid"`) Visual variant of the input
prefix - string | LucideIcon Text or icon to display at the beginning of the input
suffix - string | LucideIcon Text or icon to display at the end of the input
showAsterisk - boolean Whether to display an asterisk in the label for required fields
leftIcon - LucideIcon Optional icon to display on the left side
rightIcon - LucideIcon Optional icon to display on the right side
max - number Maximum value allowed for the input
value - number Controlled value (number) for the input
defaultValue - number | null Default value (number) for uncontrolled use
onChange - (event, originalValue, maskedValue) => void Callback function called when the value changes, receives the event, original value, and formatted value
Other properties
All other standard HTML properties of <input> are also supported, except type, max, defaultValue, value, and onChange, which are controlled by the component.

Notes

  • The type type is not supported because it is controlled by the mask.
  • Formatting is applied automatically as the user types.
  • When isLoading is true, input is automatically disabled.
  • Formatting follows international standards for each currency localization.
On this page