International Currencies

Especially when there's a mix of currencies on the page, we strongly suggest using ISO 4217 currency codes (e.g. USD, EUR, BRL) to ensure proper understanding of currencies and improve user experience.

Use the format="code" prop to force the display of the three-letter currency code, which is useful for clarity in these multi-currency contexts.

If you absolutely need to hardcode a symbol, don't assume $ will always be understood as American dollars. $ and other currency symbols might be used in more than one country (e.g. American Dollar - $, Canadian Dollar - $) causing confusion to users.

When you're unsure if the user is from the US, prefer using currency codes.

You should respect user locale for displaying currencies. By default, Currency will use the user's browser or system locale to format. This will affect symbol, code, decimal, and thousand separators. Only override the locale for strong business reasons.

When designing or improving data models and APIs, try to make them locale- and timezone-aware.

Here's a list of all available locale codes.

On the localization topic, not all currencies use two decimal places so, set decimal precision according to the currency (e.g. 0 for JPY and 2 for USD). Allow dynamic precision when needed.

The Currency component defaults to 0 for currencies that do not support fractions.

Here's a complete list of currency decimal places

Make sure ink components provide you with the necessary formats for your localized product. If that's not the case, reach out to the #ink channel or the #wg-i18n channel and make your request, or contribute by opening a PR and adding your format. Don't forget to add tests!

When displaying values for entities that operate in multiple currencies, use the primaryCurrency and code props to clarify which currency is primary and how to display the value (symbol vs. code).

This is how these two props interact with each other:

These are also influenced by the locale so, make sure you're using the correct combination of props.

primaryCurrency doesn't work by itself. It needs code to work the display logic.

When numbers are part of financial reports and explicitly show gains and losses, first make sure the country you're working with has the same connotations for colors as in colorize (green for positive, red for negative).

By using the colorize prop, Currency will automatically visually distinguish positive (green) and negative (red) values.

If you are unsure if colorize is correct for the country you're working with, prefer leaving the prop out of the component or reach out to the ink team to explore other options.

Make sure to always test your UI with different combinations of locale, code and primaryCode to ensure correct formatting, truncation, spacing, symbol placement, and separators.

Use a combination of format, explicit and colorize props to control display and clarity of information.

Clearly document which fields are currency-sensitive in your APIs and UI, and communicate with designers and translators about currency formatting requirements.