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

title: formatNum
description: Format numbers, currency, percentages, and numeric values without a GT instance. API reference for formatNum.

---

[`formatNum`](/docs/platform/core/reference/gt-class-methods/formatting/format-num) is a standalone utility function from General Translation's Core library that formats numbers according to locale-specific conventions. It returns a locale-aware string for decimals, currency, percentages, and units.

## Overview [#overview]

Import `formatNum` directly from `generaltranslation` and call it with the number to format and an options object. It does not require an API key or a [GT](/docs/platform/core/reference/gt-class/constructor) instance, so use it anywhere you need one-off number formatting. For instance-based formatting that inherits the instance locale, use the [`formatNum`](/docs/platform/core/reference/gt-class-methods/formatting/format-num) method on a [`GT`](/docs/platform/core/reference/gt-class/constructor) instance instead.

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

const formatted = formatNum(1234.56, {
  locales: 'de-DE',
  style: 'currency',
  currency: 'EUR',
});
// Returns: "1.234,56 €"
```

Signature:

```typescript
formatNum(
  number: number,
  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) as the GT class method, so all standard `Intl.NumberFormat` options are supported.
- **Locale resolution.** When `locales` is an array, locales are tried in order and the first supported locale is used. When `locales` is omitted, it falls back to the library default locale, `en`.
- **Caching.** Results are cached internally for performance across repeated locale and options combinations.

## Parameters [#parameters]

| Parameter | Description | Type | Optional | Default |
| --- | --- | --- | --- | --- |
| [`number`](#number) | The number to format. | `number` | No | — |
| [`options`](#options) | Formatting configuration, including the target locale(s) and any `Intl.NumberFormat` options. | `{ locales?: string \| string[] } & Intl.NumberFormatOptions` | Yes | `{}` |

### `number` [#number]

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

The numeric value to format.

### `options` [#options]

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

Formatting configuration. Any [`Intl.NumberFormat`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/NumberFormat) option is accepted in addition to `locales`. The most common fields:

| Property | Description | Type | Optional | Default |
| --- | --- | --- | --- | --- |
| `locales` | Locale(s) for formatting. Tried in order when an array is passed. | `string \| string[]` | Yes | `en` |
| `style` | Number formatting style. | `'decimal' \| 'currency' \| 'percent' \| 'unit'` | Yes | `'decimal'` |
| `currency` | Currency code (required when `style` is `'currency'`). | `string` | Yes | — |
| `minimumIntegerDigits` | Minimum number of integer digits (1–21). | `number` | Yes | — |
| `minimumFractionDigits` | Minimum number of fraction digits (0–20). | `number` | Yes | — |
| `maximumFractionDigits` | Maximum number of fraction digits (0–20). | `number` | Yes | — |
| `useGrouping` | Whether to use grouping separators. | `boolean \| 'always' \| 'auto' \| 'min2'` | Yes | `'auto'` |
| `notation` | Number notation format. | `'standard' \| 'scientific' \| 'engineering' \| 'compact'` | Yes | `'standard'` |

## Returns [#returns]

**Type** `string`

The number formatted according to locale conventions.

## Examples [#examples]

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

// Basic number formatting
console.log(formatNum(1234.567, { locales: 'en-US' }));
// Output: "1,234.567"

// German formatting
console.log(formatNum(1234.567, { locales: 'de-DE' }));
// Output: "1.234,567"
```

```typescript
// Currency formatting

// US Dollar
console.log(formatNum(1234.56, {
  locales: 'en-US',
  style: 'currency',
  currency: 'USD',
}));
// Output: "$1,234.56"

// Euro with German locale
console.log(formatNum(1234.56, {
  locales: 'de-DE',
  style: 'currency',
  currency: 'EUR',
}));
// Output: "1.234,56 €"

// Japanese Yen
console.log(formatNum(1234.56, {
  locales: 'ja-JP',
  style: 'currency',
  currency: 'JPY',
}));
// Output: "¥1,235"
```

## Notes [#notes]

- Uses the same underlying `Intl.NumberFormat` as the GT class method.
- Results are cached internally for performance with repeated locale/options combinations.
- Fallback locales are processed in order if the primary locale is not supported.
- All standard `Intl.NumberFormat` options are supported.