# General Translation Platform: formatNum
URL: https://generaltranslation.com/en-GB/docs/platform/core/reference/gt-class-methods/formatting/format-num.mdx
---

title: formatNum
description: Format numbers, currency, percentages, and numeric values by locale. API reference for formatNum.

---

Formats a number according to locale-specific conventions on a [GT](/docs/platform/core/reference/gt-class/constructor) instance. General Translation uses the built-in `Intl.NumberFormat` API to handle decimal separators, grouping separators, and numbering systems automatically for the target locale.

## Overview [#overview]

Call `formatNum` on a [`GT`](/docs/platform/core/reference/gt-class/constructor) instance with the number to format and an optional options object. It returns the formatted number as a string.

```typescript
const gt = new GT({ targetLocale: 'de' });

const formatted = gt.formatNum(1234.56, {
  style: 'decimal',
  minimumFractionDigits: 2,
});
// "1.234,56" (German number formatting)
```

Signature:

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

*Note: `formatNum` runs locally using `Intl.NumberFormat` and does not require an API key. By default, it formats for the instance's target locale, falling back to the source locale and then the library default (`en`); pass `locales` to override. For formatting without a `GT` instance, see the standalone [`formatNum`](/docs/platform/core/reference/utility-functions/formatting/format-num).*

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

* **Locale resolution.** By default, the method formats for the instance's target locale, falling back to the source locale and then the library default (`en`) — not the `locales` config array. Pass `locales` in the options to override it for a single call.
* **Intl-backed.** Formatting is delegated to the browser-native [`Intl.NumberFormat`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/NumberFormat), so all standard `Intl.NumberFormatOptions` are supported and locale conventions are applied automatically.
* **Style requirements.** Currency formatting requires both `style: 'currency'` and a valid `currency` code. Unit formatting requires both `style: 'unit'` and a valid `unit` identifier.

## Parameters [#parameters]

| Parameter             | Description                                                                               | Type     | Optional | Default |
| --------------------- | ----------------------------------------------------------------------------------------- | -------- | -------- | ------- |
| [`number`](#number)   | The number to format.                                                                     | `number` | No       | —       |
| [`options`](#options) | Formatting configuration, extending `Intl.NumberFormatOptions` with a `locales` override. | `object` | Yes      | —       |

### `number` [#number]

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

The number to format.

### `options` [#options]

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

Formatting configuration. Extends `Intl.NumberFormatOptions` with an additional `locales` field:

| Name                       | Description                                            | Type                                                                                                                 | Optional | Default                |
| -------------------------- | ------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------- | -------- | ---------------------- |
| `locales`                  | Override locales used for formatting.                  | `string \| string[]`                                                                                                 | Yes      | instance target locale |
| `style`                    | Number formatting style.                               | `'decimal' \| 'currency' \| 'percent' \| 'unit'`                                                                     | Yes      | `'decimal'`            |
| `currency`                 | Currency code (required when `style` is `'currency'`). | `string`                                                                                                             | Yes      | —                      |
| `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'`              |
| `minimumIntegerDigits`     | Minimum number of integer digits (1–21).               | `number`                                                                                                             | Yes      | `1`                    |
| `minimumFractionDigits`    | Minimum number of fraction digits (0–20).              | `number`                                                                                                             | Yes      | —                      |
| `maximumFractionDigits`    | Maximum number of fraction digits (0–20).              | `number`                                                                                                             | Yes      | —                      |
| `minimumSignificantDigits` | Minimum significant digits (1–21).                     | `number`                                                                                                             | Yes      | —                      |
| `maximumSignificantDigits` | Maximum significant digits (1–21).                     | `number`                                                                                                             | Yes      | —                      |
| `useGrouping`              | Whether to use grouping separators.                    | `boolean \| 'always' \| 'auto' \| 'min2'`                                                                            | Yes      | `'auto'`               |
| `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'`                                                                      | Yes      | `'auto'`               |
| `roundingMode`             | Rounding mode.                                         | `'ceil' \| 'floor' \| 'expand' \| 'trunc' \| 'halfCeil' \| 'halfFloor' \| 'halfExpand' \| 'halfTrunc' \| 'halfEven'` | Yes      | `'halfExpand'`         |
| `roundingIncrement`        | Rounding increment.                                    | `1 \| 2 \| 5 \| 10 \| 20 \| 25 \| 50 \| 100`                                                                         | Yes      | `1`                    |
| `trailingZeroDisplay`      | Whether to display trailing zeroes.                    | `'auto' \| 'stripIfInteger'`                                                                                         | Yes      | `'auto'`               |

## Returns [#returns]

**Type** `string`

The formatted number, following the target locale's conventions.

## Examples [#examples]

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

const gt = new GT({ targetLocale: 'en-US' });

// Basic decimal formatting
console.log(gt.formatNum(1234.567));
// Output: "1,234.567"

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

// French locale formatting
console.log(gt.formatNum(1234.567, { locales: 'fr-FR' }));
// Output: "1 234,567"
```

```typescript
// Currency formatting

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

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

// Currency display options
console.log(gt.formatNum(1234.56, {
  style: 'currency',
  currency: 'USD',
  currencyDisplay: 'code',
}));
// Output: "USD 1,234.56"

// Accounting format (parentheses for negative)
console.log(gt.formatNum(-1234.56, {
  style: 'currency',
  currency: 'USD',
  currencySign: 'accounting',
}));
// Output: "($1,234.56)"
```

```typescript
// Percentage and scientific notation

// Basic percentage
console.log(gt.formatNum(0.1234, { style: 'percent' }));
// Output: "12%"

// Percentage with decimal places
console.log(gt.formatNum(0.1234, {
  style: 'percent',
  minimumFractionDigits: 1,
  maximumFractionDigits: 2,
}));
// Output: "12.34%"

// Compact notation
console.log(gt.formatNum(1234567, { notation: 'compact' }));
// Output: "1.2M"

// Scientific notation
console.log(gt.formatNum(1234567, { notation: 'scientific' }));
// Output: "1.235E6"
```

## Notes [#notes]

* Number formatting automatically follows locale-specific conventions.
* The method uses browser-native `Intl.NumberFormat` for performance and accuracy.
* Currency formatting requires both `style: 'currency'` and a valid `currency` code.
* Unit formatting requires both `style: 'unit'` and a valid `unit` identifier.