# currency-formatter

> A simple Javascript utility that helps you to display currency properly

Latest version **1.5.9** (published 2021-09-29) · MIT license · 0 weekly downloads

## Install

```sh
npm install currency-formatter
pnpm add currency-formatter
yarn add currency-formatter
bun add currency-formatter
```

## Health

**Score 23/100 (F)** — status: abandoned.

Positive: has types package; no vulnerabilities; high quality score.

Warnings: low downloads; no esm support.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 1.5.9 |
| Published | 2021-09-29 |
| First published | 2015-10-14 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | separate (@types/currency-formatter) |
| Module format | CommonJS |
| Dependencies | 3 |
| Unpacked size | 55.4 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Author | Soroush Mirzaei |
| Maintainers | soroush |
| Keywords | format, currency, money |

## Links

- npm: https://www.npmjs.com/package/currency-formatter
- Repository: https://github.com/smirzaei/currency-formatter
- Homepage: https://github.com/smirzaei/currency-formatter#readme
- Issues: https://github.com/smirzaei/currency-formatter/issues
- npm.io page: https://npm.io/package/currency-formatter

## Dependencies (3)

- [accounting](https://npm.io/package/accounting.md) ^0.4.1
- [object-assign](https://npm.io/package/object-assign.md) ^4.1.1
- [locale-currency](https://npm.io/package/locale-currency.md) 0.0.2

## Alternatives

- [mobx-react](https://npm.io/package/mobx-react.md) — 2.8M weekly downloads
- [rc-tree](https://npm.io/package/rc-tree.md) — 2.6M weekly downloads
- [@react-oauth/google](https://npm.io/package/@react-oauth/google.md) — 1.3M weekly downloads
- [@wagmi/connectors](https://npm.io/package/@wagmi/connectors.md) — 877.0K weekly downloads
- [vee-validate](https://npm.io/package/vee-validate.md) — 836.4K weekly downloads

## Recent versions

- 1.5.9 (latest) — 2021-09-29
- 1.5.8 — 2021-04-29
- 1.5.7 — 2021-03-24
- 1.5.6 — 2020-08-10
- 1.5.5 — 2019-08-01
- 1.5.4 — 2019-05-14
- 1.5.3 — 2018-10-05
- 1.5.2 — 2018-10-03
- 1.5.1 — 2018-08-29
- 1.5.0 — 2018-08-28
- 1.4.5 — 2018-08-28
- 1.4.4 — 2018-08-24
- 1.4.3 — 2018-07-07
- 1.4.2 — 2018-03-02
- 1.4.1 — 2018-02-20
- … 25 more at https://npm.io/package/currency-formatter/versions

## README

# Currency Formatter

[![Build Status](https://travis-ci.org/smirzaei/currency-formatter.svg)](https://travis-ci.org/smirzaei/currency-formatter)

A simple Javascript utility that helps you to display currency properly

STOP! You probably don't need this library
=

#### TL;DR: This library was created a long time ago. You should use [Internationalization API](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/NumberFormat) instead.

Please don't add another dependency which you don't need. All modern browsers (and node.js) have this functionality built-in and do a much better job at formatting currencies. e.g. [#57](https://github.com/smirzaei/currency-formatter/issues/57)

* Browser support: https://caniuse.com/#search=intl
* Polyfill: https://github.com/andyearnshaw/Intl.js
* ECMA402 reference: https://tc39.github.io/ecma402/

Example:
```JS
new Intl.NumberFormat('en-US', { style: 'currency', currency: 'USD' }).format(100000000)
// => "$100,000,000.00"

new Intl.NumberFormat('en-US', { style: 'currency', currency: 'EUR' }).format(100000000)
// => "€100,000,000.00"

new Intl.NumberFormat('de-DE', { style: 'currency', currency: 'USD' }).format(100000000)
// => "100.000.000,00 $"

new Intl.NumberFormat('de-DE', { style: 'currency', currency: 'EUR' }).format(100000000)
// => "100.000.000,00 €"

new Intl.NumberFormat('fr-FR', { style: 'currency', currency: 'EUR' }).format(100000000)
// => "100 000 000,00 €"
```

With that being said use this library if you need:

* Your version of node.js doesn't come with the `full-icu`. See: [#72](https://github.com/smirzaei/currency-formatter/issues/72) and [#19214](https://github.com/nodejs/node/issues/19214)
* Support old browsers.
* Consistent formatting across all browsers.
* You don't like the Intl APIs
* ???


Install
=

```bash
npm install currency-formatter --save
```

Basic Usage
=

By specifying the currency code

```js
var currencyFormatter = require('currency-formatter');

currencyFormatter.format(1000000, { code: 'USD' });
// => '$1,000,000.00'

currencyFormatter.format(1000000, { code: 'GBP' });
// => '£1,000,000.00'

currencyFormatter.format(1000000, { code: 'EUR' });
// => '1 000 000,00 €'
```

Or by specifying the locale
```js
var currencyFormatter = require('currency-formatter');

currencyFormatter.format(1000000, { locale: 'en-US' });
// => '$1,000,000.00'

currencyFormatter.format(1000000, { locale: 'en-GB' });
// => '£1,000,000.00'

currencyFormatter.format(1000000, { locale: 'GB' });
// => '£1,000,000.00'

currencyFormatter.format(1000000, { locale: 'de-DE' });
// => '1.000.000,00 €'

currencyFormatter.format(1000000, { locale: 'nl-NL' });
// => '€1.000.000,00'
```

You can also get the currency information.

```JAVASCRIPT
var currencyFormatter = require('currency-formatter');

currencyFormatter.findCurrency('USD');
// returns:
// {
//   code: 'USD',
//   symbol: '$',
//   thousandsSeparator: ',',
//   decimalSeparator: '.',
//   symbolOnLeft: true,
//   spaceBetweenAmountAndSymbol: false,
//   decimalDigits: 2
// }

```

Parse the number of a monetary value

```js

currencyFormatter.unformat('$10.5', { code: 'USD' })
// => 10.5

currencyFormatter.unformat('$1,000,000', { code: 'USD' })
// => 1000000

currencyFormatter.unformat('10,5 €', { code: 'EUR' })
// => 10.5

currencyFormatter.unformat('1 000 000,00 €', { code: 'EUR' })
// => 1000000

currencyFormatter.unformat('1.000,99', { locale: 'de-DE' })
// => 1000.99

currencyFormatter.unformat('10\'000 CHF', { code: 'CHF' })
// => 10000

currencyFormatter.unformat('10.00 CHF', { code: 'CHF' })
// => 10

currencyFormatter.unformat('10,00 CHF', { code: 'CHF' })
// => 1000

```

Advanced Usage
=
Currency Formatter uses [accounting](https://github.com/openexchangerates/accounting.js) library under the hood, and you can use its options to override the default behavior.

```JAVASCRIPT
var currencyFormatter = require('currency-formatter');
currencyFormatter.format(1000000, {
  symbol: '@',
  decimal: '*',
  thousand: '^',
  precision: 1,
  format: '%v %s' // %s is the symbol and %v is the value
});

// => '1^000^000*0 @'

// Different formatting for positive and negative values
currencyFormatter.format(-10, {
  format: {
    pos: '%s%v' // %s is the symbol and %v is the value
    neg: '(%s%v)',
    zero: '%s%v'
  }
});

// => ($10)
```

You could also get a list of all the currencies here using one of the following:

```js
var currencies = require('currency-formatter/currencies');
// OR
var currencyFormatter = require('currency-formatter');
var currencies = currencyFormatter.currencies;
```

Or the currencies in hashmap shape:

```js
var currencies = require('currency-formatter/currencies.json');
// Result:
// {
//  "USD": {
//    "code": "USD",
//    "symbol": "$",
//    "thousandsSeparator": ",",
//    "decimalSeparator": ".",
//    "symbolOnLeft": true,
//    "spaceBetweenAmountAndSymbol": false,
//    "decimalDigits": 2
//  },
//  ...more currencies
// }
```

License
=
[MIT](https://github.com/smirzaei/currency-formatter/blob/master/LICENSE)

---
_Source: https://npm.io/package/currency-formatter · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._