https://github.com/awesomelabs/react-native-format-currency
A lightweight international currency formatter for React Native & Expo (iOS and Android).
https://github.com/awesomelabs/react-native-format-currency
List: react-native-format-currency
currency currency-format expo react-native
Last synced: 4 months ago
JSON representation
A lightweight international currency formatter for React Native & Expo (iOS and Android).
- Host: GitHub
- URL: https://github.com/awesomelabs/react-native-format-currency
- Owner: AwesomeLabs
- License: mit
- Created: 2021-09-08T19:26:15.000Z (almost 5 years ago)
- Default Branch: main
- Last Pushed: 2025-01-29T16:19:01.000Z (over 1 year ago)
- Last Synced: 2025-04-30T16:52:59.759Z (about 1 year ago)
- Topics: currency, currency-format, expo, react-native
- Language: JavaScript
- Homepage:
- Size: 335 KB
- Stars: 33
- Watchers: 2
- Forks: 11
- Open Issues: 3
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# react-native-format-currency
[](https://www.npmjs.com/package/react-native-format-currency)
[](https://www.npmjs.com/package/react-native-format-currency)
[](https://x.com/AwesomeLabsLLC)
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
### `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 }`
```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.
### `getSupportedCurrencies()`
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" }, ...]
```
### Cache helpers
`formatCurrency` memoizes results (LRU, max 100 entries) for speed.
```ts
import { clearFormatCache, getFormatCacheSize } from "react-native-format-currency";
console.log(getFormatCacheSize());
clearFormatCache();
```
### Currency data and types
```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/`](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`](LICENSE).