next

CurrencyFormatOptions

Object expressing options for currency formatting methods.

Syntax

object {
  style?,
  group?,
  round?,
  cash?,
  divisor?,
  symbolWidth?,
  trimZeroFractions?,
  minimumIntegerDigits?,
  maximumFractionDigits?,
  minimumFractionDigits?,
  maximumSignificantDigits?,
  minimumSignificantDigits?,
  nu?
}

Properties

  • style?: CurrencyFormatStyleType
    • Style used to format the currency value.
  • group?: boolean
    • Enable grouping of digits.
  • round?: RoundingModeType
    • Mode used to round numbers during formatting. Note that this should be used carefully when formatting currencies, as each currency defines the number of decimal digits that should appear in the result.
  • cash?: boolean
    • Activate rounding to nearest cash increment. The Canadian Dollar's eliminated the penny so cash transactions round to the nearest 0.05 increment.
  • divisor?: number
    • Specify an explicit divisor when formatting a compact style. Should be a round power of 10, e.g. 1000, 10000, etc.
  • symbolWidth?: CurrencySymbolWidthType
    • Hint to use the narrow symbol width if available.
  • trimZeroFractions?: boolean
    • Format as a whole number when the decimal digits are all zero.
  • minimumIntegerDigits?: number
    • Minimum integer digits to display.
  • maximumFractionDigits?: number
    • Maximum fraction digits to display.
  • minimumFractionDigits?: number
    • Minimum fraction digits to display.
  • maximumSignificantDigits?: number
    • Maximum significant digits to display.
  • minimumSignificantDigits?: number
    • Minimum significant digits to display.
  • nu?: NumberSystemType
    • Override the number system used to format the digits.

Defaults

{
  style: 'symbol',
  group: true,
  round: 'half-even',
  cash: false,
  symbolWidth: 'default'
}
  • Integer and fraction option defaults are determined by the selected number pattern.
  • Options for significant digits default to undefined.
  • Numbering system default is determined by the locale.

Examples

const cldr = framework.get('en');
log(cldr.Numbers.formatCurrency('12345.6789', 'EUR'));

€12,345.68

Using a compact style with an explicit fixed divisor.

const cldr = framework.get('en');
const opts = { style: 'short', divisor: 1000 };
log(cldr.Numbers.formatCurrency('100', 'USD', opts));
log(cldr.Numbers.formatCurrency('1234567', 'USD', opts));

$0.1K
$1,235K

The cash option activates rounding to the smallest cash unit available for the given currency. For example, if the penny were eliminated in the United States, the nickel ($0.05) would become the smallest cash unit available. See the CLDR currency data for the most recent list.

Note: the round rounding mode still takes effect; only the rounding increment is changed.

const cldr = framework.get('en');
const opts = { cash: true };

// The smallest cash unit for the Danish Krone is 0.50
log(cldr.Numbers.formatCurrency('345.67', 'DKK', opts));
log(cldr.Numbers.formatCurrency('345.76', 'DKK', opts));

// The smallest cash unit for the Canadian Dollar is 0.05
log(cldr.Numbers.formatCurrency('345.67', 'CAD', opts));
log(cldr.Numbers.formatCurrency('345.76', 'CAD', opts));

DKK 345.50
DKK 346.00
CA$345.65
CA$345.75

The trimZeroFractions option can display the amount as a whole number when possible.

const cldr = framework.get('en');
for (const n of ['10', '10.9999', '10.10', '10.23']) {
  log(cldr.Numbers.formatCurrency(n, 'USD', { trimZeroFractions: true }));
}

$10
$11
$10.10
$10.23

Note that the minimumFractionDigits option will override trimZeroFractions. Explicit adjustment of decimal fraction digits should never be used for currencies unless you know what you're doing.

const cldr = framework.get('en');
for (const n of ['10', '10.9999', '10.10', '10.23']) {
  log(
    cldr.Numbers.formatCurrency(n, 'USD', {
      trimZeroFractions: true,
      minimumFractionDigits: 3,
    })
  );
}

$10.000
$11.000
$10.100
$10.230

References

← MessageMatcherCurrencyFormatStyleType →