# General Translation React SDKs (gt-react, gt-next, gt-react-native): `<Currency>`
URL: https://generaltranslation.com/en-US/docs/react/reference/components/currency.mdx
Docs index: https://generaltranslation.com/llms.txt
Description: Format a currency amount for the active locale. API reference for the `<Currency>` component.

The `<Currency>` component renders a numeric value formatted as a currency for the active locale. It only formats — it does not perform exchange-rate conversion.

*Available in `gt-react`, `gt-next`, `gt-tanstack-start`, and `gt-react-native`.*

## Overview [#overview]

Pass an amount as children and set the `currency` code.

```tsx
<Currency>{100}</Currency>
// Output: $100.00
```

All formatting is handled locally with [`Intl.NumberFormat`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/NumberFormat).

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

- **Local formatting.** The amount is formatted in the browser using `Intl.NumberFormat`. Its value is never sent to the General Translation API.
- **No conversion.** `<Currency>` formats the symbol, grouping, and decimals for the chosen currency and locale, but does not convert between currencies.
- **Locale resolution.** The active locale determines formatting unless overridden with `locales`.

## Props [#props]

| Prop | Description | Type | Optional | Default |
| --- | --- | --- | --- | --- |
| [`children`](#children) | The amount to format. | `number \| string` | No | — |
| [`currency`](#currency) | ISO 4217 currency code. | `string` | Yes | `USD` |
| [`options`](#options) | `Intl.NumberFormat` options. | `Intl.NumberFormatOptions` | Yes | `{}` |
| [`locales`](#locales) | Locale override for formatting. | `string[]` | Yes | Active locale |
| [`name`](#name) | Variable name for the entry. | `string` | Yes | — |

### `children` [#children]

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

The amount to format as currency. Strings are parsed into numbers before formatting.

### `currency` [#currency]

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

The ISO 4217 currency code, such as `USD` or `EUR`. It determines the symbol and formatting.

### `options` [#options]

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

The prop accepts [`Intl.NumberFormatOptions`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/NumberFormat/NumberFormat#options). Common 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 | `'latn'` |
| `style` | Number-formatting style. | `'decimal' \| 'currency' \| 'percent' \| 'unit'` | Yes | `'currency'` |
| `currency` | ISO 4217 currency code. Overrides the top-level `currency` prop when provided here. | `string` | Yes | `currency` prop |
| `currencyDisplay` | How to display the currency. | `'code' \| 'symbol' \| 'narrowSymbol' \| 'name'` | Yes | `'symbol'` |
| `currencySign` | Standard or accounting notation for negative values. | `'standard' \| 'accounting'` | Yes | `'standard'` |
| `unit` | Unit identifier used if `style` is changed to `'unit'`. | `string` | Yes | — |
| `unitDisplay` | Width of the unit label. | `'long' \| 'short' \| 'narrow'` | Yes | `'short'` |
| `minimumIntegerDigits` | Minimum integer digits; shorter values are zero-padded. | `number` (`1`–`21`) | Yes | `1` |
| `minimumFractionDigits` | Minimum digits after the decimal separator. | `number` (`0`–`100`) | Yes | Currency-dependent |
| `maximumFractionDigits` | Maximum digits after the decimal separator. | `number` (`0`–`100`) | Yes | Currency-dependent |
| `minimumSignificantDigits` | Minimum significant digits. | `number` (`1`–`21`) | Yes | `1` |
| `maximumSignificantDigits` | Maximum significant digits. | `number` (`1`–`21`) | Yes | `21` |
| `roundingPriority` | Whether fraction or significant digits take priority. | `'auto' \| 'morePrecision' \| 'lessPrecision'` | Yes | `'auto'` |
| `roundingIncrement` | Increment used at the selected rounding magnitude. | `1 \| 2 \| 5 \| 10 \| 20 \| 25 \| 50 \| 100 \| 200 \| 250 \| 500 \| 1000 \| 2000 \| 2500 \| 5000` | Yes | `1` |
| `roundingMode` | Direction used when rounding. | `'ceil' \| 'floor' \| 'expand' \| 'trunc' \| 'halfCeil' \| 'halfFloor' \| 'halfExpand' \| 'halfTrunc' \| 'halfEven'` | Yes | `'halfExpand'` |
| `trailingZeroDisplay` | Whether to keep trailing zeros on whole numbers. | `'auto' \| 'stripIfInteger'` | Yes | `'auto'` |
| `notation` | Standard, scientific, engineering, or compact notation. | `'standard' \| 'scientific' \| 'engineering' \| 'compact'` | Yes | `'standard'` |
| `compactDisplay` | Long or short labels for compact notation. | `'short' \| 'long'` | Yes | `'short'` |
| `useGrouping` | When to display grouping separators. | `boolean \| 'always' \| 'auto' \| 'min2'` | Yes | `'auto'`; `'min2'` with compact notation |
| `signDisplay` | When to display a positive or negative sign. | `'auto' \| 'always' \| 'exceptZero' \| 'negative' \| 'never'` | Yes | `'auto'` |

The component applies `style: 'currency'`, the top-level `currency` prop, and `numberingSystem: 'latn'` before applying `options`. Values provided through `options` therefore override those defaults.

- Currency fraction-digit defaults come from the currency's standard minor units.
- `compactDisplay` only applies when `notation` is `'compact'`.
- `roundingIncrement` cannot be combined with significant-digit rounding or a `roundingPriority` other than `'auto'`.
- Supported units, numbering systems, rounding fields, and option values depend on the JavaScript runtime.

See the [`Intl.NumberFormat` options documentation](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/NumberFormat/NumberFormat#options) for the latest available options and runtime behavior.

### `locales` [#locales]

**Type** `string[]` · **Optional** · **Default** Active locale

Locales to format for. When omitted, the active locale is used. See the [locales argument](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl#locales_argument).

### `name` [#name]

**Type** `string` · **Optional**

An optional name for the currency field, used for metadata.

## Examples [#examples]

*Examples import from `gt-react`; import from your framework's package instead.*

```tsx title="PriceDisplay.tsx"
import { Currency } from 'gt-react';

export default function PriceDisplay({ item }) {
  return <Currency>{item.price}</Currency>; // [!code highlight]
}
```

```tsx title="PriceDisplay.tsx"
import { Currency } from 'gt-react';

export default function PriceDisplay({ item }) {
  return <Currency currency="EUR">{item.price}</Currency>; // [!code highlight]
}
```

```tsx title="PriceDisplay.tsx"
import { T, Currency } from 'gt-react';

export default function PriceDisplay({ item }) {
  return (
    <T>
      The price is <Currency>{item.price}</Currency>. // [!code highlight]
    </T>
  );
}
```

```tsx title="PriceDisplay.tsx"
import { Currency } from 'gt-react';

export default function PriceDisplay({ item }) {
  return (
    <Currency
      currency="GBP"
      options={{ // [!code highlight]
        currencyDisplay: 'narrowSymbol',
        minimumFractionDigits: 2,
        maximumFractionDigits: 2,
      }}
    >
      {item.price}
    </Currency>
  );
}
```

## Notes [#notes]

- `<Currency>` formats currency values for the active locale; it does not convert between currencies.
- Its contents are formatted locally and never sent to the API.

## Sitemap

See the full [sitemap](https://generaltranslation.com/sitemap.md) for all pages.