# General Translation Platform: formatCurrency
URL: https://generaltranslation.com/en-US/docs/platform/core/reference/utility-functions/formatting/format-currency.mdx
---

title: formatCurrency
description: Format a currency value by locale without a GT instance. API reference for formatCurrency.

---

[`formatCurrency`](/docs/platform/core/reference/gt-class-methods/formatting/format-currency) is a standalone utility function from General Translation's Core library that formats a numeric value as a localized currency string. It wraps the built-in `Intl.NumberFormat` API with the currency style.

## Overview [#overview]

Import `formatCurrency` directly from `generaltranslation` and call it with a value, a currency code, and an options object. It does not require an API key or a [GT](/docs/platform/core/reference/gt-class/constructor) instance. For instance-based formatting that inherits the instance locale, use the [`formatCurrency`](/docs/platform/core/reference/gt-class-methods/formatting/format-currency) method on a [`GT`](/docs/platform/core/reference/gt-class/constructor) instance instead.

```typescript
import { formatCurrency } from 'generaltranslation';

const price = formatCurrency(1234.56, 'EUR', { locales: ['de-DE'] });
// "1.234,56 €"
```

Signature:

```typescript
formatCurrency(
  value: number,
  currency: string,
  options?: { locales?: string | string[] } & Intl.NumberFormatOptions
): string
```

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

- **Underlying API.** Uses the same [`Intl.NumberFormat`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/NumberFormat) with `style: 'currency'` as the GT class method.
- **Locale resolution.** When `locales` is omitted, it falls back to the library default locale, `en`.
- **Symbol placement.** The currency symbol, grouping separators, and decimal format follow the resolved locale.

## Parameters [#parameters]

| Parameter | Description | Type | Optional | Default |
| --- | --- | --- | --- | --- |
| [`value`](#value) | The numeric amount to format. | `number` | No | — |
| [`currency`](#currency) | The ISO 4217 currency code, such as `USD` or `EUR`. | `string` | No | — |
| [`options`](#options) | Formatting configuration, including the target locale(s). | `{ locales?: string \| string[] } & Intl.NumberFormatOptions` | Yes | `{}` |

### `value` [#value]

**Type** `number` · **Required**

The numeric amount to format.

### `currency` [#currency]

**Type** `string` · **Required**

The ISO 4217 currency code, such as `USD`, `EUR`, or `JPY`.

### `options` [#options]

**Type** `{ locales?: string | string[] } & Intl.NumberFormatOptions` · **Optional** · **Default** `{}`

Formatting configuration. The table lists common currency options exposed by the published Core types and their effective Core defaults. See the [`Intl.NumberFormat` constructor options](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/NumberFormat/NumberFormat#options) for supplemental standard and runtime-specific details.

| Property | Description | Type | Optional | Default |
| --- | --- | --- | --- | --- |
| `locales` | Locale(s) for formatting. | `string \| string[]` | Yes | `en` |
| `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. `formatCurrency` supplies the currency style unless you override it. | `'decimal' \| 'currency' \| 'percent' \| 'unit'` | Yes | `'currency'` |
| `currency` | Currency code used by the formatter. The positional `currency` argument supplies this value unless you override it. | `string` | Yes | positional `currency` argument |
| `currencyDisplay` | How to display the currency. | `'symbol' \| 'narrowSymbol' \| 'code' \| 'name'` | Yes | `'symbol'` |
| `currencySign` | Currency sign to use. | `'standard' \| 'accounting'` | Yes | `'standard'` |
| `unit` | Unit identifier. Required when `style` is `'unit'`. | `string` | Yes | — |
| `unitDisplay` | How to display the unit. | `'short' \| 'narrow' \| 'long'` | Yes | `'short'` |
| `minimumFractionDigits` | Minimum fraction digits (0–100). | `number` | Yes | currency minor-unit digits; `0` with compact defaults |
| `maximumFractionDigits` | Maximum fraction digits (0–100), at least `minimumFractionDigits`. | `number` | Yes | currency minor-unit digits; `0` with compact defaults |
| `minimumSignificantDigits` | Minimum significant digits (1–21), when significant-digit rounding is active. | `number` | Yes | `1` |
| `maximumSignificantDigits` | Maximum significant digits (1–21), when significant-digit rounding is active. | `number` | Yes | `21`; `2` with compact defaults |
| `roundingPriority` | How fraction- and significant-digit settings interact. | `'auto' \| 'morePrecision' \| 'lessPrecision'` | Yes | `'auto'`; `'morePrecision'` with compact defaults |
| `roundingMode` | Rounding mode. | `'ceil' \| 'floor' \| 'expand' \| 'trunc' \| 'halfCeil' \| 'halfFloor' \| 'halfExpand' \| 'halfTrunc' \| 'halfEven'` | Yes | `'halfExpand'` |
| `roundingIncrement` | Rounding increment. Non-default values require equal effective minimum and maximum fraction digits and cannot be combined with significant-digit rounding or a non-`'auto'` `roundingPriority`. | `1 \| 2 \| 5 \| 10 \| 20 \| 25 \| 50 \| 100 \| 200 \| 250 \| 500 \| 1000 \| 2000 \| 2500 \| 5000` | Yes | `1` |
| `useGrouping` | Whether and when to use grouping separators. | `boolean \| 'always' \| 'auto' \| 'min2'` | Yes | `'auto'`; `'min2'` with compact defaults |
| `notation` | Number notation format. | `'standard' \| 'scientific' \| 'engineering' \| 'compact'` | Yes | `'standard'` |
| `compactDisplay` | Compact notation display style. | `'short' \| 'long'` | Yes | `'short'` |
| `signDisplay` | When to display the sign. | `'auto' \| 'never' \| 'always' \| 'exceptZero' \| 'negative'` | Yes | `'auto'` |
| `trailingZeroDisplay` | Whether to display trailing zeros. | `'auto' \| 'stripIfInteger'` | Yes | `'auto'` |

When `notation: 'compact'` is set without any fraction- or significant-digit option, the effective digit defaults are `minimumFractionDigits: 0`, `maximumFractionDigits: 0`, `minimumSignificantDigits: 1`, and `maximumSignificantDigits: 2`. In that case, `roundingPriority` defaults to `'morePrecision'` and `useGrouping` defaults to `'min2'`. Setting `style: 'unit'` also requires a valid `unit`.

## Returns [#returns]

**Type** `string`

The value formatted as a localized currency string.

## Examples [#examples]

```typescript
import { formatCurrency } from 'generaltranslation';

// US dollars
console.log(formatCurrency(1234.56, 'USD', { locales: 'en-US' }));
// Output: "$1,234.56"

// Euros, German locale
console.log(formatCurrency(1234.56, 'EUR', { locales: 'de-DE' }));
// Output: "1.234,56 €"

// Japanese yen (no fractional digits)
console.log(formatCurrency(1234, 'JPY', { locales: 'ja-JP' }));
// Output: "￥1,234"
```

## Notes [#notes]

- Always pass an explicit `locales` value for correct, deterministic output.
- Pass any `Intl.NumberFormatOptions` (for example, `minimumFractionDigits`) alongside `locales` to fine-tune the output.