Dinero.js

Features

• Immutable and chainable API.
• Global settings support.
• Extended formatting and rounding options.
• Native Intl support (no additional locale files).
• Currency conversion.

Download/install

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.

UMD (browser global)

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

CommonJS (Node)

const Dinero = require('dinero.js')

You will need at least Node 6+ with full-icu support.

AMD (RequireJS, System.js, etc.)

requirejs(['path/to/amd/dinero'], function(Dinero) {   //... })

ES modules (modern browser, Webpack, etc.)

import Dinero from 'path/to/esm/dinero.js'

TypeScript

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.

Quick start

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.

Read full documentation

Contributing

Pull requests are welcome! Please check the contributing guidelines for install instructions and general conventions.

Community

Selected content about Dinero.js:

• JSJ 351: Dinero.js with Sarah Dayan
• Build a Shopping Cart with Vue and Dinero.js
• How to Handle Monetary Values in JavaScript
• Comparison with Numeral.js
• Submit your own blog post/tutorial!

Support

Show some love by upvoting on Product Hunt if you like, support and/or use the library 🔼😍

Acknowledgements

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.

License

Dinero.js is licensed under MIT.