Format Currency

formatCurrency

The formatCurrency function formats a number or numeric string as a locale-aware currency string, automatically handling symbol placement, decimal separators, and grouping. It uses the built-in Intl.NumberFormat API for accurate localization.

Function Signature

function formatCurrency(
  value: Numeric,
  currency?: CurrencyCode,
  locale?: LocaleCode
): string

Parameters

• value (Numeric): The number or numeric string to format (e.g., 42 or "42.50").
• currency (CurrencyCode, optional): ISO 4217 currency code. Defaults to 'USD'.
• locale (LocaleCode, optional): BCP 47 locale code. Defaults to auto-detected based on currency.

Example Usage

Notes

• Automatic Locale Detection: If no locale is provided, it uses a mapping (e.g., USD → en-US, EUR → de-DE, BDT → bn-BD).
• Negative Values: Formats negative numbers according to the specified locale (e.g., -42 → -$42.00).
• Numeric Strings: Gracefully accepts and coerces numeric string values.

Types

Numeric

type Numeric = number | `${number}`;

CurrencyCode

type CurrencyCode = keyof typeof CURRENCY_LOCALES | (typeof CURRENCY_CODES)[number];

LocaleCode

type LocaleCode = (typeof CURRENCY_LOCALES)[keyof typeof CURRENCY_LOCALES] | (typeof LOCALE_CODES)[number];

Aliases

• convertNumberToCurrency