Click here for v1.x documentation.
Dinero.js
Dinero.js version

Quick start

Copy linkInstall 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>

Copy linkInstall 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>

Copy linkFirst 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.

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

You can display Dinero objects into any format, exactly the way you want. Dinero.js lets you build a formatter that exposes a pre-formatted amount, in units and in stringified decimal format (if the currency is decimal and single-base).

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

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

toFormat(d1, ({ decimal, currency }) => `${currency.code} ${decimal}`); // "USD 50.00"
toFormat(d2, ({ units }) => `${units[0]} ariary, ${units[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.