formatMoney

number |> (
  currency: text,
  locale: text,
  decimals: number|nothing,
  includeCurrency: boolean|nothing
) => text

Formats an amount with an ISO 4217 currency code for display in the given BCP-47 locale.

formatMoney renders an amount together with its ISO 4217 currency code. The presentation follows the locale: when the currency is the locale’s native one you get the native form (1 299,50 kr), otherwise the ISO-code form (12,34 USD).

The default decimal places follow the currency — 2 for most, 0 for JPY-style currencies, 3 for KWD-style ones. Override with decimals, and hide the currency label entirely with includeCurrency: false.

Examples

Native currency in its locale

import { formatMoney } from 'text'

from 1299.5 formatMoney ('SEK', 'sv-SE')

// Returns:
// '1 299,50 kr'

A foreign currency uses the ISO-code form

import { formatMoney } from 'text'

from 12.34 formatMoney ('USD', 'sv-SE')

// Returns:
// '12,34 USD'

Currency-driven decimal places

import { formatMoney } from 'text'

from 1300 formatMoney ('JPY', 'ja-JP')

// Returns:
// '￥1,300'

import { formatMoney } from 'text'

from 1300 formatMoney ('JPY', 'sv-SE')

// Returns:
// '1 300 JPY'

Override the decimals

import { formatMoney } from 'text'

from 1299.5 formatMoney ('SEK', 'sv-SE', 0)

// Returns:
// '1 300 kr'

Amount only, no currency label

import { formatMoney } from 'text'

from 1299.5 formatMoney ('SEK', 'sv-SE', nothing, false)

// Returns:
// '1 299,50'

Unresolvable locales fall back to invariant, ungrouped

import { formatMoney } from 'text'

from 1299.5 formatMoney ('SEK', 'xx-BAD', 3)

// Returns:
// '1299.500 SEK'

Notes

• The decimals default is the currency’s minor-unit digits from ISO 4217: 2 for most currencies, 0 for JPY-style (BIF, CLP, ISK, KRW, VND, …), 3 for KWD-style (BHD, IQD, JOD, KWD, …)
• decimals requests are rounded to a whole number and clamped to 0–28
• includeCurrency defaults to true; when false the amount renders alone but the digits still default from the currency — that is the point of passing a currency whose label you are hiding
• The native-symbol form is the culture’s currency presentation for its own currency, so it varies by locale