react-native-format-currency

A lightweight currency formatter for React Native and Expo. Format amounts using ISO 4217 currency codes with correct symbol placement and common thousands/decimal separator styles.

• Zero runtime deps (pure JS/TS)
• 165+ currencies
• Typed (TypeScript declarations included)
• Fast (memoized with a small LRU cache)

Install

yarn add react-native-format-currency

npm install react-native-format-currency

pnpm add react-native-format-currency

Quick start

import { formatCurrency } from "react-native-format-currency";

const [withSymbol, withoutSymbol, symbol] = formatCurrency({
  amount: 1234.56,
  code: "USD",
});

// withSymbol: "$1,234.56"
// withoutSymbol: "1,234.56"
// symbol: "$"

API

formatCurrency({ amount, code, returnType? })

Formats a numeric amount for a given ISO 4217 currency code.

• Params
  • amount: number: the numeric amount (negative supported)
  • code: string: ISO 4217 currency code (e.g. "USD", "EUR", "JPY")
  • returnType?: "array" | "object": optional return format (default: "array")
• Returns
  • Array (default): [formattedWithSymbol, formattedWithoutSymbol, symbol]
  • Object: { formatted, value, symbol }

import { formatCurrency } from "react-native-format-currency";

// Array format (default)
formatCurrency({ amount: 1234.56, code: "ARS" });
// ["$ 1.234,56", "1.234,56", "$"]

formatCurrency({ amount: -99.99, code: "GBP" });
// ["-£99.99", "-99.99", "£"]

// Object format
formatCurrency({ amount: 1234.56, code: "USD", returnType: "object" });
// { formatted: "$1,234.56", value: "1,234.56", symbol: "$" }

Notes

• Formatting is based on this package's internal currency rules (symbol, separators, symbol position, decimals). It does not take a locale argument.
• For floating-point sensitive values, consider passing integers (e.g. cents) and dividing/rounding prior to formatting.

getSupportedCurrencies()

Returns all supported currencies as { code, name }[].

import { getSupportedCurrencies } from "react-native-format-currency";

const currencies = getSupportedCurrencies();
// [{ code: "AED", name: "United Arab Emirates Dirham" }, ...]

Cache helpers

formatCurrency memoizes results (LRU, max 100 entries) for speed.

import { clearFormatCache, getFormatCacheSize } from "react-native-format-currency";

console.log(getFormatCacheSize());
clearFormatCache();

Currency data and types

import type { CurrencyCode, CurrencyConfig, FormatResult, FormatResultObject, SupportedCurrency } from "react-native-format-currency";
import { CURRENCIES } from "react-native-format-currency";

• CURRENCIES: full currency config map (symbols, separators, etc.)
• CurrencyCode: union of supported ISO currency codes
• FormatResult: array return type [string, string, string]
• FormatResultObject: object return type { formatted, value, symbol }

Example app

The repo includes an Expo example in example/.

cd example
yarn install
yarn start

If Expo complains about your Node version, use an LTS-compatible Node version required by the Expo SDK you’re running (see Expo’s docs for the current requirement).

Development

yarn install
yarn build
yarn test

Contributing

• Please open an issue (or a PR) for bugs/feature requests.
• Keep changes small and add/adjust tests where relevant.

Security

Please do not open public issues for security vulnerabilities. Prefer reporting privately via the project’s maintainer contact (see package.json / GitHub profile).

License

MIT — see LICENSE.