currency.js v2.0.4

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 253 (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/currency.js@~1.1.0/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().

pattern default: !# Allows you to customize the format pattern using ! as replacement for the currency symbol and # as replacement for the currency amount.

negativePattern default: -!# Allows you to customize the negative format pattern using ! as replacement for the currency symbol and # as replacement for the currency amount.

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

increment default: null When implementing a currency that implements rounding, setting the increment value will allow you to set the closest increment to round the display value to. currency(1.48, { increment: .05 }); // => 1.50

useVedic default: false Formats number groupings using the Indian Numbering System, i.e. 10,00,000.00

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 experimental babel plugin for transforming currency operations currency(1.23) + 4.56 to currency(1.23).add(4.56).

Other Libraries

Maybe currency.js isn't the right fit for your needs. Check out some of these other fine libraries:

• accounting.js
• dinero.js
• walletjs

License

MIT