shepherdwind / currency.js

A javascript library for handling currencies

currency.js

currency.js is a lightweight ~1kb javascript library for working with currency values. It was built to work around floating point issues in javascript. This talk by Bartek Szopka explains in detail why javascript has floating point issues.

currency.js works with values as integers behind the scenes, resolving some of the most basic precision problems.

2.51 + .01;                   // 2.5199999999999996
currency(2.51).add(.01);      // 2.52

2.52 - .01;                   // 2.5100000000000002
currency(2.52).subtract(.01); // 2.51

This should work for most reasonable values of currencies. As long as your currency values are less than 2⁵³ (in cents) or 90,071,992,547,409.91 you should be okay.

Installation

With npm:

npm install --save currency.js

With yarn:

yarn add currency.js

Via cdn:

<script src="https://unpkg.com/[email protected]/dist/currency.min.js"></script>

Usage

Currency will accept numbers, strings, or the currency object itself as values.

currency(123);      // 123.00
currency(1.23);     // 1.23
currency("1.23")    // 1.23
currency("$12.30")  // 12.30

var value = currency("123.45");
currency(value);    // 123.45

There's various arithmetic methods that help take the guesswork out of trying to resolve floating point problems.

currency(123.50).add(0.23);       // 123.73
currency(5.00).subtract(0.50);    // 4.50
currency(45.25).multiply(3);      // 135.75
currency(1.12).distribute(5);     // [0.23, 0.23, 0.22, 0.22, 0.22]

There's even a built in formatter that will automatically place comma delimiters in the right place.

currency("2,573,693.75").add("100,275.50").format();  // "2,673,969.25"
currency("1,237.72").subtract(300).format();          // "937.72"

You can also change the format, localizing the decimal and/or delimiter to your locale.

var euro = value => currency(value, { separator: ".", decimal: "," });
euro("2.573.693,75").add("100.275,50").format();  // "2.673.969,25"
euro("1.237,72").subtract(300).format();          // "937,72"

Options

currency.js comes with its own set of default options conforming to USD. You can customize these according to your locale.

symbol default: $
When formatWithSymbol is set to true, will include the currency symbol when calling currency.format().

separator default: ,
Separator dividing the number groups when calling currency.format().

decimal default: .
Decimal used when calling currency.format().

precision default: 2
Number of decimal places to store as cents.

formatWithSymbol default: false
Includes the symbol option when calling currency.format().

errorOnInvalid default: false
If an invalid value such as null or undefined is passed in, will throw an error.

View more examples and full documentation at scurker.github.io/currency.js.

v1.0.0 breaking changes

In all version prior to v1.0.0, currency options were global. These global options were removed in v1.0.0 and now are passed to each instance of currency.js as the second param. This allows you to set options without any unintended side effects.

v0.4.x

currency.settings.separator = " ";
currency.settings.decimal = ",";
currency.settings.symbol = "€";
currency.settings.formatWithSymbol = true;

v1.x

currency(1.23, { separator: " ", decimal: ",", symbol: "€", formatWithSymbol: true })

If you need to work with multiple currency values, the easiest way is to setup factory functions with your required currency settings.

const USD = value => currency(value, { symbol: "$", precision: 2 });
const JPY = value => currency(value, { symbol: "¥", precision: 0 });
const GAS = value => currency(value, { precision: 3 });

USD(1234.56).format(true); // "$1,234.56"
JPY(1234.56).format(true); // "¥1,235"
GAS(1234.56).format(true); // "$1,234.560"

Add-ons

• babel-plugin-transform-currency-operators: An experiental babel plugin for transforming currency operations currency(1.23) + 4.56 to currency(1.23).add(4.56).

License

MIT