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

Formatting

When working with money on the front end, comes a time when you need to display amounts on the user interface. The Dinero.js API provides functions to format objects.

import { dinero, toUnit, down } from 'dinero.js';
import { USD } from '@dinero.js/currencies';

const d = dinero({ amount: 1055, currency: USD });

toUnit(d, { digits: 1, round: down }); // 10.5

Copy linkDisplaying an object

Dinero objects are ideal to safely manipulate money, but at some point, you need to display them. The toFormat function lets you display objects the way you want. It exposes a pre-formatted amount for convenience.

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

const transformer = ({ amount, currency }) => `${currency.code} ${amount}`;

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

toFormat(d, transformer); // "USD 50"

Dinero.js uses the scale of the object to determine how many decimal places to represent. You can adjust it in the transformer.

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

const transformer = ({ amount, currency }) => `${currency.code} ${amount.toFixed(1)}`;

const d = dinero({ amount: 4545, currency: USD });

toFormat(d, transformer, options); // "USD 45.5"

If you're formatting many objects, you might want to reuse the same transformer without having to pass it every time. To do so, you can write your own higher-order function to build formatters.

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

// This function lets you pass a transformer and rounding options.
// It returns a function that takes a Dinero object and applies
// the closured transformer.
function createFormatter(transformer) {
  return function formatter(dineroObject) {
    return toFormat(dineroObject, transformer);
  };
}

// This function is reusable to format any Dinero object
// with the same transformer.
const format = createFormatter(
  ({ amount, currency }) => `${currency.code} ${amount}`
);

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

format(d); // "USD 50"

Copy linkRetrieving raw data

One of the most convenient formatting functions in Dinero.js is toSnapshot. Its primary usage isn't the front end but to take snapshots of Dinero objects to inspect them.

Whenever you need to access a Dinero object's raw data, toSnapshot is the go-to function.

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

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

toSnapshot(d);

// {
//   amount: 5000,
//   currency: {
//     code: 'EUR',
//     base: 10,
//     exponent: 2,
//   },
//   scale: 2,
// }

Another useful usage of toSnapshot is transport and storage. To do so, check the advanced guide on transporting and restoring.