dinero.js Documentation

v2 has dropped built-in support for locales to remain dependency-free. To replicate the formatting behavior from v1.x, you must create a custom formatter that wraps the native Intl API using toDecimal.

import { toDecimal } from 'dinero.js';

function createIntlFormatter(locale, options = {}) {
  function transformer({ value, currency }) {
    return Number(value).toLocaleString(locale, {
      ...options,
      style: 'currency',
      currency: currency.code,
    });
  }

  return function formatter(dineroObject) {
    return toDecimal(dineroObject, transformer);
  };
}

export const intlFormat = createIntlFormatter('en-US');

// Usage:
// intlFormat(dineroObject) -> "$5.00"

You can install dinero.js using npm or yarn. For projects not using a package manager, you can include it via a CDN script tag.

npm install dinero.js

# or

yarn add dinero.js

Dinero.js provides standard ISO 4217 currency objects via specific subpath exports.

For standard numeric amounts, import from dinero.js/currencies. For bigint amounts, import from dinero.js/bigint/currencies.

Warning: Currency data may change between Dinero.js versions. If you require absolute stability, define your own custom currency objects or pin your Dinero.js version.

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

const d1 = dinero({ amount: 1000, currency: USD });
const d2 = dinero({ amount: 1000, currency: EUR });

Install this skill to teach your AI agent currency handling patterns. It covers: defining type-safe custom currencies, compile-time currency mismatch detection, validating currency codes from external sources, converting with scaled exchange rates, database storage schemas, and payment service integration (Stripe, PayPal, Square).

npx skills add dinerojs/skills --skill dinero-currency-patterns

The compare function is designed to be used directly as a comparator for Array.prototype.sort() to sort lists of Dinero objects.

• Ascending (Low to High): Pass compare directly to .sort().
• Descending (High to Low): Use an arrow function to reverse the arguments: (a, b) => compare(b, a).

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

const d1 = dinero({ amount: 900, currency: USD });
const d2 = dinero({ amount: 500, currency: USD });
const d3 = dinero({ amount: 800, currency: USD });

const lowToHigh = [d1, d2, d3].sort(compare);
const highToLow = [d1, d2, d3].sort((a, b) => compare(b, a));

If a currency is not available in the built-in library, you can define your own object. A custom currency must include a code, base, and exponent.

const FRF = {
  code: 'FRF',
  base: 10,
  exponent: 2,
};

For representing colossal amounts of money or high-exponent cryptocurrencies that exceed the safe limits of the JavaScript number type, use the bigint variant of Dinero.js.

Important: You must import dinero and currencies from the dinero.js/bigint subpaths. Do not mix currencies from dinero.js/currencies with the bigint variant, as they use number for base and exponent.

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

const d1 = dinero({ amount: 500n, currency: USD });
const d2 = dinero({ amount: 100n, currency: USD });

add(d1, d2); // a Dinero object with amount `600n`

When using TypeScript, Dinero.js uses the TCurrency type parameter to represent currency codes as string literal types. This allows the compiler to catch currency mismatches in operations like add, subtract, equal, compare, greaterThan, greaterThanOrEqual, lessThan, lessThanOrEqual, minimum, maximum, haveSameAmount, and normalizeScale before runtime.

Built-in ISO 4217 currencies (like USD or EUR) are pre-typed to enable this behavior automatically.

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

const d1 = dinero({ amount: 500, currency: USD }); // Dinero<number, 'USD'>
const d2 = dinero({ amount: 100, currency: USD }); // Dinero<number, 'USD'>
const d3 = dinero({ amount: 100, currency: EUR }); // Dinero<number, 'EUR'>

add(d1, d2); // OK
add(d1, d3); // Type error: 'EUR' is not assignable to 'USD'

Dinero.js objects must be instantiated using integers representing the minor currency units (e.g., cents for USD). To avoid precision issues, do not pass floats directly to the dinero() constructor.

If you have float amounts (like 19.99), you should implement a helper function to convert the float into the appropriate integer amount based on the currency's scale/exponent before calling dinero().

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

// Standard way: use integers (minor units)
const d = dinero({ amount: 1999, currency: USD });

// Helper for floats
function dineroFromFloat({ amount: float, currency, scale }) {
  const factor = currency.base ** (scale ?? currency.exponent);
  const amount = Math.round(float * factor);

  return dinero({ amount, currency, scale });
}