# General Translation Platform: formatNum URL: https://generaltranslation.com/en-GB/docs/platform/core/reference/gt-class-methods/formatting/format-num.mdx Docs index: https://generaltranslation.com/llms.txt 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. The table lists common 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 supplementary standard and runtime-specific details). | Name | Description | Type | Optional | Default | | -------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- | -------- | ---------------------------------------------------------------------------------------------------- | | `locales` | Override locales used for formatting. | `string \| string[]` | Yes | `targetLocale` → `sourceLocale` → `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. | `'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 fraction digits (0–100). The style affects the default. | `number` | Yes | `0` for decimal/percent; currency minor-unit digits for currency; `0` with compact defaults | | `maximumFractionDigits` | Maximum fraction digits (0–100). The style and minimum affect the default. | `number` | Yes | `3` for decimal; `0` for percent; currency minor-unit digits for currency; `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 | | `notation` | Number notation format. | `'standard' \| 'scientific' \| 'engineering' \| 'compact'` | Yes | `'standard'` | | `compactDisplay` | Compact notation display style. | `'short' \| 'long'` | Yes | `'short'` | | `useGrouping` | Whether and when to use grouping separators. | `boolean \| 'always' \| 'auto' \| 'min2'` | Yes | `'auto'`; `'min2'` with compact notation | | `signDisplay` | When to display the sign. | `'auto' \| 'never' \| 'always' \| 'exceptZero' \| 'negative'` | Yes | `'auto'` | | `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` | | `trailingZeroDisplay` | Whether to display trailing zeroes. | `'auto' \| 'stripIfInteger'` | Yes | `'auto'` | When `notation: 'compact'` is set without any fractional- 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'`. ## 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. ## Sitemap See the full [sitemap](https://generaltranslation.com/sitemap.md) for all pages.