Skip to content
A javascript library for handling currencies
Branch: master
Clone or download
scurker Merge pull request #187 from scurker/renovate/flow-bin-0.x
chore(deps): update dependency flow-bin to ^0.95.0
Latest commit 86fb18e Mar 15, 2019
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
config chore(deps): update dependency google-closure-compiler-js to v20181028 ( Nov 7, 2018
docs fix example Mar 6, 2019
src fix flow type by using class + static callable instead Oct 6, 2018
test
.babelrc
.browserslistrc
.eslintignore
.eslintrc
.flowconfig
.gitattributes
.gitignore
.travis.yml revert to default travis npm install Nov 6, 2018
ava.config.js
bower.json
changelog.md v1.2.1 Oct 6, 2018
license remove url from license, restore copyright year Oct 7, 2018
package-lock.json chore(deps): update dependency flow-bin to ^0.95.0 Mar 15, 2019
package.json chore(deps): update dependency flow-bin to ^0.95.0 Mar 15, 2019
readme.md v1.2.0 Sep 26, 2018
renovate.json preserve semver, don't pin Nov 6, 2018

readme.md

currency.js logo

currency.js

Build Status Coverage Status npm gzip size

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.2.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

Other Libraries

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

License

MIT

You can’t perform that action at this time.