How to show currency as symbol, code, or name

Use the currencyDisplay option to control whether currencies appear as $, USD, or US dollars

Introduction

When you display a price or monetary amount, you need to decide how to represent the currency. A product price might display as $25, USD 25, or 25 US dollars. Each format serves a different purpose and works better in different contexts.

The symbol format works well for everyday shopping interfaces where users know what currency to expect. The code format removes ambiguity in international business documents where multiple currencies appear. The name format provides maximum clarity for accessibility tools and educational content.

JavaScript provides the currencyDisplay option in Intl.NumberFormat to control how currencies appear. This lesson explains the four available formats, how they differ across locales, and which format to choose for your specific use case.

Understanding the currencyDisplay option

The currencyDisplay option controls how the currency unit appears when formatting monetary amounts. It does not change the numeric value, only how the currency is represented.

Four values are available:

  • symbol displays a localized currency symbol like $ or €
  • narrowSymbol displays a compact symbol like $ instead of US$
  • code displays the ISO currency code like USD or EUR
  • name displays the full currency name like US dollars or euros

Each format creates a different visual representation of the same amount. The choice depends on your user interface requirements, available space, and audience expectations.

Using symbol format for everyday displays

The symbol format is the default currencyDisplay value. It shows a localized currency symbol that users in a given locale expect to see.

const formatter = new Intl.NumberFormat('en-US', {
  style: 'currency',
  currency: 'USD',
  currencyDisplay: 'symbol'
});

console.log(formatter.format(25));
// Output: "$25.00"

This format produces the most familiar representation for users. Americans expect to see dollar signs, Europeans expect to see euro symbols, and British users expect to see pound symbols.

The symbol adapts based on both the locale and the currency. When you format US dollars for a German locale, the formatter uses a localized symbol that includes the country designation.

const usFormatter = new Intl.NumberFormat('en-US', {
  style: 'currency',
  currency: 'USD',
  currencyDisplay: 'symbol'
});

console.log(usFormatter.format(25));
// Output: "$25.00"

const deFormatter = new Intl.NumberFormat('de-DE', {
  style: 'currency',
  currency: 'USD',
  currencyDisplay: 'symbol'
});

console.log(deFormatter.format(25));
// Output: "25,00 $"

Notice how the German formatter places the dollar sign after the amount and uses a comma for the decimal separator. These locale-specific conventions apply automatically.

When you format euros for different locales, the euro symbol appears but the formatting conventions change.

const usFormatter = new Intl.NumberFormat('en-US', {
  style: 'currency',
  currency: 'EUR',
  currencyDisplay: 'symbol'
});

console.log(usFormatter.format(25));
// Output: "€25.00"

const deFormatter = new Intl.NumberFormat('de-DE', {
  style: 'currency',
  currency: 'EUR',
  currencyDisplay: 'symbol'
});

console.log(deFormatter.format(25));
// Output: "25,00 €"

The symbol format works well when users operate within a single currency context. A US e-commerce site showing prices in USD can safely use dollar signs. A European site showing prices in EUR can use euro symbols.

However, the symbol format can create ambiguity when multiple currencies share similar symbols. Canadian dollars, Australian dollars, and US dollars all use the dollar sign. In these cases, some locales add a country prefix to disambiguate.

const usFormatter = new Intl.NumberFormat('en-US', {
  style: 'currency',
  currency: 'CAD',
  currencyDisplay: 'symbol'
});

console.log(usFormatter.format(25));
// Output: "CA$25.00"

The formatter adds CA$ to distinguish Canadian dollars from US dollars when formatting for a US locale.

Using narrowSymbol format for compact displays

The narrowSymbol format displays the currency symbol without country prefixes. This creates a more compact representation that works well in space-constrained interfaces.

const symbolFormatter = new Intl.NumberFormat('en-US', {
  style: 'currency',
  currency: 'USD',
  currencyDisplay: 'symbol'
});

console.log(symbolFormatter.format(25));
// Output: "$25.00"

const narrowFormatter = new Intl.NumberFormat('en-US', {
  style: 'currency',
  currency: 'USD',
  currencyDisplay: 'narrowSymbol'
});

console.log(narrowFormatter.format(25));
// Output: "$25.00"

For US dollars in a US locale, both formats produce the same output because no country prefix is needed. The difference becomes apparent when formatting currencies that might otherwise include a country designation.

const symbolFormatter = new Intl.NumberFormat('en-US', {
  style: 'currency',
  currency: 'CAD',
  currencyDisplay: 'symbol'
});

console.log(symbolFormatter.format(25));
// Output: "CA$25.00"

const narrowFormatter = new Intl.NumberFormat('en-US', {
  style: 'currency',
  currency: 'CAD',
  currencyDisplay: 'narrowSymbol'
});

console.log(narrowFormatter.format(25));
// Output: "$25.00"

The narrow symbol format removes the CA prefix, showing just the dollar sign. This saves space but loses the distinction between Canadian and US dollars.

Use narrowSymbol when space is limited and the currency context is clear from other parts of the interface. Mobile apps, compact dashboards, and data tables benefit from the shorter format. However, ensure users can determine which currency they are viewing through other means, such as a currency selector or header label.

The narrow format also affects other currencies across different locales.

const narrowFormatter = new Intl.NumberFormat('de-DE', {
  style: 'currency',
  currency: 'EUR',
  currencyDisplay: 'narrowSymbol'
});

console.log(narrowFormatter.format(25));
// Output: "25,00 €"

Each locale defines its own narrow symbol format based on local conventions.

Using code format for unambiguous displays

The code format displays the ISO 4217 currency code instead of a symbol. This three-letter code uniquely identifies each currency without ambiguity.

const formatter = new Intl.NumberFormat('en-US', {
  style: 'currency',
  currency: 'USD',
  currencyDisplay: 'code'
});

console.log(formatter.format(25));
// Output: "USD 25.00"

The code appears in place of the symbol, making it immediately clear which currency the amount represents. This format works across all locales with consistent abbreviations.

const usFormatter = new Intl.NumberFormat('en-US', {
  style: 'currency',
  currency: 'EUR',
  currencyDisplay: 'code'
});

console.log(usFormatter.format(25));
// Output: "EUR 25.00"

const deFormatter = new Intl.NumberFormat('de-DE', {
  style: 'currency',
  currency: 'EUR',
  currencyDisplay: 'code'
});

console.log(deFormatter.format(25));
// Output: "25,00 EUR"

The EUR code appears in both formats, though the position and number formatting follow locale conventions. This combination of universal currency codes with locale-specific number formatting makes the code format valuable for international contexts.

The code format eliminates confusion between currencies that share symbols.

const usdFormatter = new Intl.NumberFormat('en-US', {
  style: 'currency',
  currency: 'USD',
  currencyDisplay: 'code'
});

console.log(usdFormatter.format(25));
// Output: "USD 25.00"

const cadFormatter = new Intl.NumberFormat('en-US', {
  style: 'currency',
  currency: 'CAD',
  currencyDisplay: 'code'
});

console.log(cadFormatter.format(25));
// Output: "CAD 25.00"

const audFormatter = new Intl.NumberFormat('en-US', {
  style: 'currency',
  currency: 'AUD',
  currencyDisplay: 'code'
});

console.log(audFormatter.format(25));
// Output: "AUD 25.00"

Each dollar variant receives a distinct code. Users can immediately distinguish between US dollars, Canadian dollars, and Australian dollars.

Use the code format in financial reports, international invoices, accounting systems, and any context where currency clarity is critical. The format also works well in APIs and data exports where symbols might cause encoding issues.

The trade-off is reduced familiarity. Most consumers recognize $ but may not immediately know what CAD represents. Use codes when your audience understands them or when precision outweighs familiarity.

Using name format for maximum clarity

The name format displays the full currency name in the locale's language. This provides complete clarity about which currency the amount represents.

const formatter = new Intl.NumberFormat('en-US', {
  style: 'currency',
  currency: 'USD',
  currencyDisplay: 'name'
});

console.log(formatter.format(25));
// Output: "25.00 US dollars"

The currency name appears spelled out, leaving no ambiguity about what the amount represents. This format is especially valuable for accessibility. Screen readers can pronounce currency names clearly, while symbols might be announced inconsistently.

The name adapts to the locale, displaying in the appropriate language.

const enFormatter = new Intl.NumberFormat('en-US', {
  style: 'currency',
  currency: 'EUR',
  currencyDisplay: 'name'
});

console.log(enFormatter.format(25));
// Output: "25.00 euros"

const deFormatter = new Intl.NumberFormat('de-DE', {
  style: 'currency',
  currency: 'EUR',
  currencyDisplay: 'name'
});

console.log(deFormatter.format(25));
// Output: "25,00 Euro"

const frFormatter = new Intl.NumberFormat('fr-FR', {
  style: 'currency',
  currency: 'EUR',
  currencyDisplay: 'name'
});

console.log(frFormatter.format(25));
// Output: "25,00 euros"

English uses euros, German uses Euro, and French uses euros. The API handles these linguistic variations automatically, including plural forms where appropriate.

Different currencies show their names in the appropriate language for each locale.

const enFormatter = new Intl.NumberFormat('en-US', {
  style: 'currency',
  currency: 'JPY',
  currencyDisplay: 'name'
});

console.log(enFormatter.format(1000));
// Output: "1,000 Japanese yen"

const deFormatter = new Intl.NumberFormat('de-DE', {
  style: 'currency',
  currency: 'JPY',
  currencyDisplay: 'name'
});

console.log(deFormatter.format(1000));
// Output: "1.000 Japanische Yen"

English shows Japanese yen while German shows Japanische Yen. This localization helps users understand unfamiliar currencies in their own language.

Use the name format when clarity is more important than space. Educational content, accessibility-focused interfaces, and contexts where users may encounter unfamiliar currencies benefit from spelled-out names. The format also works well for voice interfaces where currency names are easier to process than symbols.

The trade-off is space. Currency names are significantly longer than symbols or codes. A compact mobile interface might struggle to fit 25.00 US dollars where $25.00 would work fine.

Choosing the right display format

Select your currencyDisplay value based on space constraints, audience familiarity, and ambiguity concerns.

Use symbol for everyday interfaces where users operate in a single currency. E-commerce sites, pricing pages, and consumer applications work well with symbols. Users recognize symbols quickly and symbols take minimal space.

Use narrowSymbol when space is extremely limited and the currency context is clear. Mobile apps, compact tables, and dashboard widgets benefit from the shorter format. Ensure the currency is identified elsewhere in the interface.

Use code when you need to distinguish between multiple currencies without ambiguity. Financial applications, currency converters, international business tools, and accounting systems need the precision that codes provide. The format also works well in technical contexts where symbols might cause issues.

Use name when maximum clarity is required. Accessibility-focused interfaces, educational content, voice interfaces, and contexts with unfamiliar currencies benefit from spelled-out names. The format also helps users learning about international currencies.

You can provide multiple views of the same data by letting users toggle between formats. A financial dashboard might show symbols by default with an option to switch to codes for detailed analysis. A currency converter might use codes in the interface but display names in tooltips.

Consider your user's expertise level. Financial professionals understand currency codes. General consumers expect symbols. International users may need codes to distinguish currencies. Users with accessibility needs benefit from names.

Combining currencyDisplay with other options

The currencyDisplay option works with all other number formatting options. You can control decimal places, rounding, and sign display while choosing your currency format.

const formatter = new Intl.NumberFormat('en-US', {
  style: 'currency',
  currency: 'USD',
  currencyDisplay: 'code',
  minimumFractionDigits: 2,
  maximumFractionDigits: 2
});

console.log(formatter.format(25.5));
// Output: "USD 25.50"

The code format appears with the specified decimal place settings. You can combine currencyDisplay with any other option like signDisplay, notation, or custom rounding rules.

Different display formats work with accounting notation.

const formatter = new Intl.NumberFormat('en-US', {
  style: 'currency',
  currency: 'USD',
  currencyDisplay: 'name',
  currencySign: 'accounting'
});

console.log(formatter.format(-25));
// Output: "(25.00 US dollars)"

The accounting format parentheses combine with the spelled-out currency name.

What to remember

The currencyDisplay option controls how currency units appear in formatted amounts. Use symbol for familiar everyday displays, narrowSymbol for compact space-constrained interfaces, code for unambiguous international contexts, and name for maximum clarity and accessibility.

Choose the format based on your available space, user expertise, and whether ambiguity between currencies is a concern. Combine currencyDisplay with other formatting options to create the exact representation your application needs.