toUnits

TOutput = TAmount[]

Get the amount of a Dinero object in units.

This function returns the total amount divided into each unit and sub-unit, as an array. For example, an object representing $10.45 expressed as 1045 (with currency USD and no custom scale) would return [10, 45] for 10 dollars and 45 cents.

When specifying multiple bases, the function returns as many units as necessary.

Copy linkParameters

Name	Type	Description	Required
`dineroObject`	`Dinero<TAmount>`	The Dinero object to format.	Yes
`transformer`	`Transformer<TAmount, TOutput>`	An optional transformer function.	No

Copy linkCode examples

Copy linkFormat an object in units

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

const d1 = dinero({ amount: 1050, currency: USD });
const d2 = dinero({ amount: 10545, currency: USD, scale: 3 });

toUnits(d1); // [10, 50]
toUnits(d2); // [10, 545]

Copy linkFormat a non-decimal object

import { dinero, toUnits } from 'dinero.js';

const GRD = { code: 'GRD', base: 6, exponent: 1 };
const d = dinero({ amount: 9, currency: GRD });

toUnits(d); // [1, 3]

Copy linkFormat an object with multiple subdivisions

import { dinero, toUnits } from 'dinero.js';

const GBP = { code: 'GBP', base: [20, 12], exponent: 1 };
const d = dinero({ amount: 267, currency: GBP });

toUnits(d); // [1, 2, 3]

Copy linkUse a custom transformer

If you need to further transform the value before returning it, you can pass a custom function.

import { dinero, toUnits } from 'dinero.js';

const GBP = { code: 'GBP', base: [20, 12], exponent: 1 };
const d = dinero({ amount: 267, currency: GBP });

const labels = ['pounds', 'shillings', 'pence'];

toUnits(d, ({ value }) =>
  value
    .filter((amount) => amount > 0)
    .map((amount, index) => `${amount} ${labels[index]}`)
    .join(', ')
);