Currency.js - Financial Calculations

2.0.4 · active · verified Sun Apr 19

currency.js is a lightweight JavaScript library specifically designed for accurate financial calculations and handling currency values, aiming to circumvent common floating-point precision issues inherent in JavaScript's number type. The current stable version is 2.0.4, with recent releases primarily focusing on critical bug fixes related to the `fromCents` option and minor security updates to development dependencies. The library provides a simple, fluent API for creating currency objects, performing arithmetic operations (add, subtract, multiply, divide), and robust formatting capabilities. It supports various international currency formats, custom patterns, and precision settings, making it a suitable choice for applications requiring reliable money management without the overhead of larger, more complex financial libraries. Its key differentiator is its small footprint and dedicated focus on fixed-point arithmetic for ensuring precision in monetary calculations.

Common errors

```
TypeError: currency.js: formatter option must be a function or object
```
cause Using a string as the value for the `formatter` option, which is no longer supported since v2.0.0.

fix Change the `formatter` option to either a function that returns the formatted string or an object specifying formatting properties. Example: `{ formatter: (value) => `$${value}` }` or `{ formatter: { symbol: '$', separator: ',', decimal: '.' } }`.
```
Incorrect currency value after using fromCents option.
```
cause The input value when `fromCents: true` is interpreted directly as cents since v2.0.0. Also, bugs in `v2.0.0` through `v2.0.3` caused incorrect calculations when `fromCents` was active.

fix For versions `v2.0.4` and above, ensure your input value is the exact number of cents (e.g., `currency(2500, { fromCents: true })` for $25.00). If you are on an older `v2.x` release, upgrade to `v2.0.4` or newer to resolve the calculation bugs.
```
Unformatted number instead of currency string.
```
cause Forgetting to call the `.format()` method on a `currency.js` object, or incorrect formatting options.

fix Always call `.format()` on the `currency` object instance to get the formatted string (e.g., `myCurrencyValue.format()`). Review options like `pattern`, `separator`, `decimal`, and `symbol` for correct display.

Warnings

breaking The `formatter` option within `currency.js` options object no longer exclusively accepts a string pattern. It now accepts either a function for fine-tuned customization or a static object defining formatting rules. Direct string patterns for `formatter` will no longer work as expected.
Fix: If you were using a string for the `formatter` option, you must update your code to either provide a function that returns the formatted string, or an object with specific formatting properties like `symbol`, `separator`, etc.
breaking The behavior of parsing input values has changed when the `fromCents` option is enabled. Previously, inputs were always treated as standard decimal values; with `fromCents`, the input number is now interpreted directly as the total number of cents (e.g., `currency(100, { fromCents: true })` now represents $1.00, not $100.00 interpreted as cents).
Fix: Review all instances where `fromCents: true` is used. Adjust your input values accordingly to ensure they represent the total cents rather than decimal currency amounts.
gotcha Multiple bugs in early v2.x releases (v2.0.1, v2.0.2, v2.0.3) led to incorrect values being returned from methods, particularly when the `fromCents` option was in use. These issues could result in incorrect calculations or truncated fractional cents.
Fix: Upgrade to `currency.js@2.0.4` or later to ensure correct calculations, especially when using the `fromCents` option. Thoroughly test your application's financial logic after upgrading.
gotcha Between v1.2.0 and v1.2.1, there were adjustments to internal precision and flow definitions. While intended to fix edge cases, subtle differences in rounding or calculation results might occur compared to versions prior to v1.2.0.
Fix: If migrating from versions older than `1.2.0`, re-verify critical financial calculations to ensure consistent results, as internal precision handling was adjusted.

Install

npm install currency.js npm
yarn add currency.js yarn
pnpm add currency.js pnpm

Imports

currency
wrong:
```
import { currency } from 'currency.js';
```
correct:
```
import currency from 'currency.js';
```
The primary `currency` function is typically imported as a default export.
CurrencyJs
```
import currency, { type CurrencyJs } from 'currency.js';
```
When using TypeScript, the `CurrencyJs` type represents the instance returned by the `currency` function, allowing for type-safe operations.
currency (CommonJS)
```
const currency = require('currency.js');
```
For CommonJS environments (e.g., older Node.js projects), `require` is used to import the library.

Quickstart

This quickstart demonstrates basic instantiation, arithmetic operations, custom formatting, and handling values explicitly as cents.

import currency from 'currency.js';

// Create a currency object
const price = currency(1234.56);

// Perform arithmetic operations
const tax = price.multiply(0.0825); // Calculate 8.25% tax
const shipping = currency(15.99);
const total = price.add(tax).add(shipping);

console.log(`Original Price: ${price.format()}`);
console.log(`Tax Amount: ${tax.format()}`);
console.log(`Shipping Cost: ${shipping.format()}`);
console.log(`Total Amount: ${total.format()}`);

// Using custom options
const euroPrice = currency(100.50, { symbol: '€', separator: '.', decimal: ',' });
const discount = currency(10, { symbol: '€', separator: '.', decimal: ',' });
const finalEuroPrice = euroPrice.subtract(discount);

console.log(`Euro Price: ${euroPrice.format()}`);
console.log(`Final Euro Price after discount: ${finalEuroPrice.format()}`);

// Handling values as cents
const valueInCents = currency(2500, { fromCents: true }); // Represents $25.00
console.log(`Value from cents: ${valueInCents.format()}`);

view raw JSON →