Hidden

Overview

Converts an amount from one currency to another.

amount.convert(/currency/, /rate/, <rounding>);

Features

• Simple and intuitive API
• Type safety with Amount and CurrencyCode
• Non-empty and valid currency check
• Rate validation including isFinite check
• Early return when converting to same currency with rate 1
• Currency codes converted to uppercase automatically
• Whitespace trimming from currency code
• Comprehensive testing

Arguments

Arg	Type	Default Value	Required
currency	CurrencyCode	-	Yes
rate	number	-	Yes
rounding	math | bank	math	No

Usage

The convert method should consider a ratio value much like the ones exposed by common exchange APIs. For instance, here’s one by Fixer:

{
    "success": true,
    "timestamp": 1519296206,
    "base": "EUR",
    "date": "2025-09-25",
    "rates": {
        "AUD": 1.566015,
        "CAD": 1.560132,
        "CHF": 1.154727,
        "CNY": 7.827874,
        "GBP": 0.882047,
        "JPY": 132.360679,
        "USD": 1.23396,
    [...]
    }
}

Before using convert, you should fetch the ratios for a given currency and then, pass the proper value to the function.

import { amount } from '@inpulse-ui/utils';

const ratios = {
  "base": "EUR",
  "rates": {
    "USD": 1.23396
  }
};
const { rates } = ratios;
const value = amount.set(19.99, 'EUR');
const targetValue = amount.convert(value, 'USD', rates['USD']); // $24.65

Other services like FastForex, ExchangeRatiosAPI and Open Exchange Rates offer a similar API response and should work properly with our function.