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

``sh
yarn add react-native-format-currency
`

`sh
npm install react-native-format-currency
`

`sh
pnpm add react-native-format-currency
`

Quick start

`ts
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

$3

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 }

`ts
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.

$3

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

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

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

$3

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

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

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

$3

`ts
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/.

`sh
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

`sh
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`.