amount.mdx

title	description
Amount	Passing an amount to a new Dinero object.

The amount is one of the three pieces of domain data necessary to create a Dinero object. It's expressed in the smallest subdivision of the currency, as an integer.

For example, 50 US dollars equal to 5,000 cents.

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

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

You should always pass integers. The library throws whenever you try to pass a float or any non-integer value.

Dinero.js comes with a number implementation, but the library is generic. This means you can use it with any data type you want: bigint, third-parties like big.js, etc. To do so, check the advanced guide on using different amount types.

No minor units

When using a currency with no minor units, you should express the amount in major units.

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

// This represents 5,000 Japanese yens
const d = dinero({ amount: 5000, currency: JPY });

When working with currencies with no minor units, you need to set the currency exponent to 0.

Non-decimal currencies

When using a non-decimal currency, you should express the amount in the smallest subdivision. If the currency has multiple subdivisions (such as the pre-decimal British pound sterling), you can specify them with an array.

import { dinero } from 'dinero.js';

// Ancient Greek drachma
const GRD = {
  code: 'GRD',
  base: 6,
  exponent: 1,
};

// This represents 1 ancient Greek drachma
// or 6 obols
const d1 = dinero({ amount: 6, currency: GRD });

// Pre-decimal Great Britain pound sterling
// 20 shillings in a pound
// 12 pence in a shilling
const GBP = {
  code: 'GBP',
  base: [20, 12],
  exponent: 1,
};

// This represents 50 pre-decimal Great Britain pounds
// or 1,000 shillings, or 12,000 pence
const d2 = dinero({ amount: 12000, currency: GBP });

When working with non-decimal currencies, you need to set the currency exponent to 1.

<Panel groups={[ { label: 'Guides', links: [ { title: 'Formatting non-decimal currencies', url: '/docs/guides/formatting-non-decimal-currencies', }, ], }, ]} />