# vue: <Currency>
URL: https://generaltranslation.com/en-US/docs/vue/reference/components/currency.mdx
---

title: "<Currency>"
description: Format a currency amount for the active locale. API reference for the <Currency> component.

---

The `<Currency>` component formats a required numeric `value` with `Intl.NumberFormat` currency style. It changes the display format but does not convert an amount between currencies.

## Overview [#overview]

Bind the amount through `value` and optionally select an ISO 4217 currency code:

```vue
<Currency :value="100" currency="EUR" />
<!-- en-US: €100.00 -->
```

Use it on its own or as a runtime variable inside [`<T>`](/docs/vue/reference/components/t).

## How it works [#how-it-works]

- A number is formatted locally in currency style. The amount is not translated or sent for currency conversion.
- A string must represent an entire number. Whitespace-only strings and `null` render empty; an invalid numeric string renders unchanged.
- `currency` defaults to `USD`. The component always applies its top-level `currency` prop and currency style after merging `options`, so `options.currency` and `options.style` cannot override them.
- Formatter slot children are ignored. Always provide `value` and use a self-closing tag.
- The component adds no HTML wrapper.

### Locale resolution

When the active locale is the configured default locale, formatting uses only that default and ignores `locales`. At any other active locale, a standalone formatter tries explicit `locales` first, then the active locale, and finally the default locale.

Inside [`<T>`](/docs/vue/reference/components/t), source fallback content uses the default locale. Translated content tries the active locale and then the default, and an explicit `locales` prop is ignored.

## Props [#props]

| Prop | Description | Type | Optional | Default |
| --- | --- | --- | --- | --- |
| [`value`](#value) | Currency amount to format. | `number \| string \| null` | No | — |
| [`currency`](#currency) | ISO 4217 currency code. | `string` | Yes | `USD` |
| [`options`](#options) | Additional `Intl.NumberFormat` options. | `Intl.NumberFormatOptions` | Yes | `{}` |
| [`locales`](#locales) | Preferred formatting locales. | `string[]` | Yes | Locale resolution order |

### `value`

**Type** `number | string | null` · **Required**

The complete numeric amount to format. Numeric strings are converted with `Number()` before formatting. The value remains in the selected currency; no exchange rate is applied.

### `currency`

**Type** `string` · **Optional** · **Default** `USD`

An ISO 4217 code such as `USD`, `EUR`, or `JPY`. This prop controls the currency even when `options` includes a different `currency` field.

### `options`

**Type** `Intl.NumberFormatOptions` · **Optional** · **Default** `{}`

Additional options forwarded to `Intl.NumberFormat`. Common currency-formatting options include:

| Option | Description | Type | Optional | Default |
| --- | --- | --- | --- | --- |
| `localeMatcher` | Locale matching algorithm. | `'lookup' \| 'best fit'` | Yes | `'best fit'` |
| `numberingSystem` | Numbering system, such as `latn` or `arab`. | `string` | Yes | Locale-dependent |
| `currencyDisplay` | How the currency is displayed. | `'code' \| 'symbol' \| 'narrowSymbol' \| 'name'` | Yes | `'symbol'` |
| `currencySign` | Standard or accounting notation for negative values. | `'standard' \| 'accounting'` | Yes | `'standard'` |
| `minimumIntegerDigits` | Minimum integer digits. | `number` | Yes | `1` |
| `minimumFractionDigits` | Minimum fraction digits. | `number` | Yes | Currency-dependent |
| `maximumFractionDigits` | Maximum fraction digits. | `number` | Yes | Currency-dependent |
| `minimumSignificantDigits` | Minimum significant digits. | `number` | Yes | `1` |
| `maximumSignificantDigits` | Maximum significant digits. | `number` | Yes | `21` |
| `useGrouping` | When to display grouping separators. | `boolean \| string` | Yes | Notation-dependent |
| `notation` | Number notation. | `'standard' \| 'scientific' \| 'engineering' \| 'compact'` | Yes | `'standard'` |
| `compactDisplay` | Compact-notation label width. | `'short' \| 'long'` | Yes | `'short'` |
| `signDisplay` | When to display a sign. | `'auto' \| 'always' \| 'exceptZero' \| 'negative' \| 'never'` | Yes | `'auto'` |
| `roundingMode` | Direction used when rounding. | `string` | Yes | Runtime-dependent |

The component forces `style: 'currency'` and the top-level `currency` value. Currency fraction-digit defaults follow that currency's standard minor units. See the [`Intl.NumberFormat` options](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/NumberFormat/NumberFormat#options) for the complete runtime-defined set.

### `locales`

**Type** `string[]` · **Optional** · **Default** Locale resolution order

Preferred BCP 47 locale codes for standalone formatting. These are tried before the active and default locales only when the active locale is not the configured default.

## Examples [#examples]

```vue title="OrderTotal.vue"
<script setup lang="ts">
import { Currency, T } from 'gt-vue';

defineProps<{ total: number }>();
</script>

<template>
  <T>
    Your total is
    <Currency
      :value="total"
      currency="EUR"
      :options="{ currencyDisplay: 'code' }"
    />.
  </T>
</template>
```