Dinero.js is a library for working with monetary values in JavaScript. It provides a comprehensive API for creating, manipulating, and formatting monetary amounts, ensuring precision and avoiding common pitfalls associated with floating-point arithmetic.
Creating Dinero Objects
You can create Dinero objects by specifying the amount in minor currency units (e.g., cents) and the currency code.
const Dinero = require('dinero.js');
const amount = Dinero({ amount: 5000, currency: 'USD' });Arithmetic Operations
Dinero.js allows you to perform arithmetic operations like addition, subtraction, multiplication, and division on monetary amounts.
const Dinero = require('dinero.js');
const amount1 = Dinero({ amount: 5000, currency: 'USD' });
const amount2 = Dinero({ amount: 3000, currency: 'USD' });
const sum = amount1.add(amount2);Formatting
You can format Dinero objects into human-readable strings using various formatting options.
const Dinero = require('dinero.js');
const amount = Dinero({ amount: 5000, currency: 'USD' });
const formatted = amount.toFormat('$0,0.00');Comparisons
Dinero.js provides methods to compare monetary amounts, such as checking if one amount is greater than, less than, or equal to another.
const Dinero = require('dinero.js');
const amount1 = Dinero({ amount: 5000, currency: 'USD' });
const amount2 = Dinero({ amount: 3000, currency: 'USD' });
const isGreater = amount1.greaterThan(amount2);Currency Conversion
Dinero.js supports currency conversion given a set of exchange rates.
const Dinero = require('dinero.js');
const amount = Dinero({ amount: 5000, currency: 'USD' });
const converted = amount.convert('EUR', { rates: { USD: 1, EUR: 0.85 } });Currency.js is a lightweight library for handling currency values in JavaScript. It provides basic arithmetic operations and formatting but lacks some of the more advanced features of Dinero.js, such as currency conversion and comprehensive comparison methods.
Accounting.js is a library for number, money, and currency formatting. While it offers robust formatting options, it does not provide the same level of precision and arithmetic operations as Dinero.js.
Dinero.js v2 is in alpha! Check it out on the
mainbranch.
Dinero.js provides builds for different environments. It also comes with polyfilled versions for older browsers.
The recommended way of install is via npm or Yarn:
npm install dinero.js --save
// or
yarn add dinero.js
You can also download the files directly or use the jsDelivr CDN.
Include Dinero.js in a script tag and access its methods through the global Dinero variable.
<script src="path/to/umd/dinero.js"></script>
<script>
Dinero();
</script>
You can use an alias if you wish:
var Money = Dinero
Any browser that supports the Internationalization API is compatible with Dinero.js. This means most browsers, and Internet Explorer 11 (this one requires the polyfilled version).
const Dinero = require('dinero.js')
You will need at least Node 6+ with full-icu support.
requirejs(['path/to/amd/dinero'], function(Dinero) {
//...
})
import Dinero from 'path/to/esm/dinero.js'
For Typescript typings, you can use the definition file from DefinitelyTyped.
npm install @types/dinero.js --save
This is a third-party file. Please report issues and open PRs for it on the DefinitelyTyped repository.
Dinero uses Number.prototype.toLocaleString, which by default isn't bundled with React Native (0.60+) on Android devices. For formatting and currency symbols to display properly, you need to change the preferred build flavor of JavaScriptCore in your project by opening ./android/app/build.gradle and changing the line def jscFlavor = 'org.webkit:android-jsc:+' to def jscFlavor = 'org.webkit:android-jsc-intl:+'.
Dinero.js makes it easy to create, calculate and format monetary values in JavaScript. You can perform arithmetic operations, extensively parse and format them, check for a number of things to make your own development process easier and safer.
Note: The library is globally available in the docs for you to be able to test it right in the browser console.
To get started, you need to create a new Dinero instance. Amounts are specified in minor currency units (e.g.: "cents" for the dollar). You can also specify an ISO 4217 currency code (default is USD).
This represents €50:
const price = Dinero({ amount: 5000, currency: 'EUR' })
You can add or subtract any amount you want, by passing it another Dinero instance:
// returns a Dinero object with amount: 5500
price.add(Dinero({ amount: 500, currency: 'EUR' }))
// returns a Dinero object with amount: 4500
price.subtract(Dinero({ amount: 500, currency: 'EUR' }))
Dinero.js is immutable, which means you'll always get a new Dinero instance when you perform any kind of transformation on it. Your original instance will remain untouched.
price // still returns a Dinero object with amount: 5000
All transformative operations return a Dinero instance, so you can chain methods away as you like:
// returns a Dinero object with amount: 4000
Dinero({ amount: 500 })
.add(Dinero({ amount: 500 }))
.multiply(4)
Note: because method calls are executed sequentially, mathematical operator precedence doesn't apply. When you execute the code above, the addition happens before the multiplication, evaluating to 4000, while 500 + 500 * 4 would normally evaluate to 2500. If you need to perform an operation before another, make sure you call it first.
You can ask all kinds of questions to your Dinero instance. You'll get a Boolean in return:
// returns true
Dinero({ amount: 500 }).equalsTo(Dinero({ amount: 500 }))
// returns false
Dinero({ amount: 100 }).isZero()
// returns true
Dinero({ amount: 1150 }).hasCents()
Because Dinero.js uses Number.toLocaleString under the hood, you can display it into any format, for any language. But no need to pass complicated objects of options to format Dinero instances to your liking. Dinero.js works with intuitive String masks:
// returns $5.00
Dinero({ amount: 500 }).toFormat('$0,0.00')
Just set the locale before you call toFormat, and you'll get a display result with the proper format:
// returns 5 000 $US
Dinero({ amount: 500000 })
.setLocale('fr-FR')
.toFormat('$0,0')
If you don't want to set the locale all the time, you can also define it globally:
Dinero.globalLocale = 'de-DE'
// returns 5.000 $
Dinero({ amount: 500000 }).toFormat('$0,0')
You can still pass a locale to your Dinero instance if you need, which will prevail over the global one. If you use a transformative method on a Dinero object, its local locale will be inherited.
// returns 10 $US
Dinero({ amount: 500 })
.setLocale('fr-FR')
.add(Dinero({ amount: 500 }))
.toFormat('$0,0')
By default, new Dinero objects represent monetary values with two decimal places. If you want to represent more, or if you're using a currency with a different exponent, you can specify a precision.
// represents $10.545
Dinero({ amount: 10545, precision: 3 })
// The Japanese yen doesn't have sub-units
// this represents ¥1
Dinero({ amount: 1, currency: 'JPY', precision: 0 })
If you're using the same currency more than once, it might be worth setting a default precision.
// The Iraqi dinar has up to 3 sub-units
Dinero.defaultCurrency = 'IQD'
Dinero.defaultPrecision = 3
// represents IQD1
Dinero({ amount: 1000 })
This is only a preview of what you can do. Dinero.js has extensive documentation with examples for all of its methods.
Pull requests are welcome! Please check the contributing guidelines for install instructions and general conventions.
Selected content about Dinero.js:
Show some love by upvoting on Product Hunt if you like, support and/or use the library 🔼😍
This project follows the all-contributors specification.
Dinero.js is inspired from Martin Fowler's monetary representation. Design-wise, it draws inspiration from Money PHP, Luxon, Moment.js and Numeral.js (even though it doesn't rely on any of them).
Logo by David DeSandro.
Dinero.js is licensed under MIT.
FAQs
An immutable library to create, calculate and format monetary values.
The npm package dinero.js receives a total of 128,359 weekly downloads. As such, dinero.js popularity was classified as popular.
We found that dinero.js demonstrated a not healthy version release cadence and project activity because the last version was released a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
PyPI confirms no security flaws were exploited in the Ultralytics supply chain attack and highlights improvements for safer package publishing.
Security News
Research
The Socket Research Team breaks down a malicious wrapper package that uses obfuscation to harvest credentials and exfiltrate sensitive data.
Research
Security News
Attackers used a malicious npm package typosquatting a popular ESLint plugin to steal sensitive data, execute commands, and exploit developer systems.
