Quick start

Install the library

To get started, you need to install the dinero.js package.

npm install dinero.js@alpha

# or

yarn add dinero.js@alpha

Then import it in your project:

// ES import
import { dinero } from 'dinero.js';

// Node.js
const { dinero } = require('dinero.js');

If you don't use a package manager, you can use the HTML script element:

<script src="https://cdn.jsdelivr.net/npm/dinero.js@alpha/dist/umd/index.production.js"></script>
<script>
  const { dinero } = window.dinero.js;
</script>

Install currencies

The Dinero.js library provides the @dinero.js/currencies package so you can have access to currency objects out of the box.

npm install @dinero.js/currencies@alpha

# or

yarn add @dinero.js/currencies@alpha

Then import it in your project:

// ES import
import { USD } from '@dinero.js/currencies';

// Node.js
const { USD } = require('@dinero.js/currencies');

If you don't use a package manager, you can use the HTML script element:

<script src="https://cdn.jsdelivr.net/npm/@dinero.js/currencies@alpha/dist/umd/index.production.js"></script>
<script>
  const { USD } = window['@dinero.js/currencies'];
</script>

INFO

You can load Dinero.js packages from jsDelivr or unpkg, or download them and host them yourself.

First steps

Dinero.js lets you express monetary values in JavaScript. You can perform mutations, conversions, comparisons, format them extensively, and overall make money manipulation in your application easier and safer.

INFO

The library is globally available in the docs for you to test it right in the browser console.

To get started, you need to create a new Dinero object. Amounts are specified in minor currency units (like "cents" for the dollar) and currencies in Currency objects.

This represents $50:

const price = dinero({ amount: 5000, currency: USD });

You can add or subtract any amount you want, by passing it another Dinero object:

import { dinero, add, subtract } from 'dinero.js';
import { USD } from '@dinero.js/currencies';

const price = dinero({ amount: 5000, currency: USD });

// returns a Dinero object with amount 6000
add(price, dinero({ amount: 1000, currency: USD }));

// returns a Dinero object with amount 4000
subtract(price, dinero({ amount: 1000, currency: USD }));

Dinero objects are immutable, meaning you always get a new Dinero object when performing transformations. Your original objects remain untouched.

price; // still returns a Dinero object with amount 5000

You can ask all kinds of questions to your Dinero objects.

import { dinero, equal, isZero, hasSubUnits } from 'dinero.js';
import { USD } from '@dinero.js/currencies';

const d1 = dinero({ amount: 500, currency: USD });
const d2 = dinero({ amount: 500, currency: USD });
equal(d1, d2); // returns true

const d3 = dinero({ amount: 100, currency: USD });
isZero(d3); // returns false

const d4 = dinero({ amount: 1150, currency: USD });
hasSubUnits(d4); // returns true

Dinero.js provides formatting functions that expose a pre-formatted amount. You can use them as-is, or pass a custom transformer function to further customize the output.

import { dinero, toDecimal, toUnits } from 'dinero.js';
import { USD, MGA } from '@dinero.js/currencies';

const d1 = dinero({ amount: 5000, currency: USD });
const d2 = dinero({ amount: 13, currency: MGA });

toDecimal(d1); // "50.00"
toDecimal(d1, ({ value, currency }) => `${currency.code} ${value}`); // "USD 50.00"
toUnits(d2, ({ value }) => `${value[0]} ariary, ${value[1]} iraimbilanja`); // "2 ariary, 3 iraimbilanja"

Dinero objects pick up their scale from their currency exponent. If you want to represent amounts differently, you can specify a scale manually.

This represents $5:

const price = dinero({ amount: 5000, currency: USD, scale: 3 });

This is only a preview of what you can do. Dinero.js provides extensive documentation with examples and guides.