Formatting localized currency

Orbit provides a currency formatting framework to:

• Help teams build products for a global audience
• Localize currency formatting for people everywhere
• Unify the display of mixed currencies when an interface works with more than one currency
• Implement the formatting through shared APIs

Definitions

An interface can present more than one type of currency and currency format.

Aligning with global standards

Orbit uses the Common Locale Data Repository (CLDR) for localization formatting of currency, date, time, and amount.

• It’s the recognized international standard
• It automatically formats numbers and currency based on the person’s locale
• The repository is maintained by a third party

CLDR determines:

• Whether the currency symbol appears before or after the amount (for example, $250, 250 USD, 250 $)
• Whether decimals are used (for example, there are no “cents” in Japanese yen)
• Whether the decimal sign is a period or a comma (for example, 37,50 or 37.50)
• How to group numbers (for example, 10,000 or 1,0000, or using spaces)

CLDR doesn’t determine the appropriate level of detail shown in different contexts. For example, it can’t determine when to show the currency symbol and value (short format), or the currency symbol, value, and ISO code (explicit format). Though short format is more efficient, it’s important to provide clarity for people who deal with unfamiliar currencies in multi-currency experiences. In those cases, use explicit format.

Design guidelines

Because CLDR formatting is limited, these guidelines will help you choose the appropriate level of currency detail to display in a multi-currency context.

Primary currency

Secondary currency

• Use explicit format when showing total amounts, an amount within a button, or in a paragraph
• Use short format when showing non-total amounts alongside total amounts

Presentment currency example: non-total amounts in short format, totals in explicit format

This example shows a scenario where the presentment currency differs from the primary currency. The non-total amounts are in short format, and the total amounts are in explicit format.

Refunding an amount in a secondary currency

This example shows a scenario refunding an amount that’s in a secondary currency.

Short format for non-total amounts in a data table

This example illustrates the use of short format for non-total amounts and explicit format for total amounts in a data table.

Negative amount display

Always place the negative symbol before the currency and amount in either format.

Bidder-facing amounts

• Default to explicit format whenever amounts are bidder-facing. Use short format for individual bids, lot estimates, and line items on an invoice.
• If there are enough indicators to let people know which currency they’re looking at, short format may be sufficient. When using short format, always use explicit format for the final hammer price, invoice total, and notification totals.

Guiding questions when making design decisions

Use the following questions to guide you when making decisions about currency formatting.

Design tips

Mock up a scenario where the primary, presentment, payout, and billing currencies are different. This scenario is increasingly common as more teams build for a global audience.

Major currencies in their local formats

This table shows commonly-used currencies in short and explicit formats.

Implementation

To format currency in a React component, use a locale-aware helper built on the platform-native Intl.NumberFormat API. Select either short or explicit formatting by setting the form option as shown below.

// Orbit relies on the platform-native Intl.NumberFormat API for
// locale-aware currency formatting. Choose "short" or "explicit"
// by toggling currencyDisplay.

function formatCurrency(
  amount: number,
  currency: string,
  locale: string,
  form: "short" | "explicit" = "short"
) {
  return new Intl.NumberFormat(locale, {
    style: "currency",
    currency,
    // "symbol" → short format ($12.50); "code" → explicit format ($12.50 USD)
    currencyDisplay: form === "explicit" ? "code" : "symbol",
  }).format(amount)
}

formatCurrency(12.5, "EUR", "de-AT", "short")
// => "€ 12,50"

formatCurrency(12.5, "EUR", "de-AT", "explicit")
// => "EUR 12,50"