JavaScript
💸 An immutable library to create, calculate and format monetary values.

Dinero.js is a library for working with monetary values in JavaScript.

See API docs

Features

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

Download/install

Dinero.js provides different builds for different environments.

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;

CommonJS (Node)

const Dinero = require('dinero.js')

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'

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.

To get started, you need to create a new Dinero instance. Amounts are specified in cents. 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')

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.

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

License

Dinero.js is licensed under MIT.