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

convert

Dinero<TAmount>

Convert a Dinero object from a currency to another.

If you need to use fractional rates, you shouldn't use floats, but scaled amounts instead. For example, instead of passing 0.89, you should pass { amount: 89, scale: 2 }. When using scaled amounts, the function converts the returned object to the safest scale.

Copy linkParameters

NameTypeDescriptionRequired
dineroObjectDinero<TAmount>

The Dinero object to convert.

Yes
newCurrencyCurrency<TAmount>

The currency to convert into.

Yes
ratesRates<TAmount>

The rates to convert with.

Yes

Copy linkCode examples

Copy linkConvert to another currency

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

const rates = { EUR: { amount: 89, scale: 2 } };
const d = dinero({ amount: 500, currency: USD });

convert(d, EUR, rates); // a Dinero object with amount 44500 and scale 4

Copy linkConvert to a currency with a different scale

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

const rates = { IQD: 1199 };
const d = dinero({ amount: 500, currency: USD });

convert(d, IQD, rates); // a Dinero object with amount 5995000 and scale 3

Copy linkBuild a reusable converter

If you're converting many objects, you might want to reuse the same rates without having to pass them every time. To do so, you can wrap convert in a converter function that accepts a Dinero object and a new currency, and returns it formatted using a predefined converter.

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

function converter(dineroObject, newCurrency) {
  return convert(dineroObject, newCurrency, { EUR: { amount: 89, scale: 2 } });
}

const converter = createConverter(rates);

converter(d, EUR); // a Dinero object with amount 44500 and scale 4

You can even build your own reusable higher-order function to build converters.

// ...

function createConverter(rates) {
  return function converter(dineroObject, newCurrency) {
    return convert(dineroObject, newCurrency, rates);
  };
}