formatNum
API reference for the formatNum method to format numbers according to locale conventions
Overview
The formatNum method formats numbers according to locale-specific conventions using the Internationalisation API.
It handles decimal separators, thousand separators, and numbering systems automatically based on the target locale.
const gt = new GT({ targetLocale: 'de' });
const formatted = gt.formatNum(1234.56, {
style: 'decimal',
minimumFractionDigits: 2
});
// Returns: "1.234,56" (German number formatting)Reference
Parameters
| Name | Type | Description |
|---|---|---|
number | number | The number to format |
options? | NumberFormatOptions | Optional formatting settings |
NumberFormatOptions
Extends Intl.NumberFormatOptions with additional locale specification:
| Name | Type | Description |
|---|---|---|
locales? | string | string[] | Override locales for formatting (defaults to instance locales) |
style? | 'decimal' | 'currency' | 'percent' | 'unit' | Number formatting style |
currency? | string | Currency code (required when style is 'currency') |
currencyDisplay? | 'symbol' | 'narrowSymbol' | 'code' | 'name' | How to display the currency |
currencySign? | 'standard' | 'accounting' | Currency sign to use |
unit? | string | Unit identifier (required when style is 'unit') |
unitDisplay? | 'short' | 'narrow' | 'long' | How to display the unit |
minimumIntegerDigits? | number | Minimum number of integer digits (1–21) |
minimumFractionDigits? | number | Minimum number of fraction digits (0–20) |
maximumFractionDigits? | number | Maximum number of fraction digits (0–20) |
minimumSignificantDigits? | number | Minimum significant digits (1–21) |
maximumSignificantDigits? | number | Maximum significant digits (1–21) |
useGrouping? | boolean | 'always' | 'auto' | 'min2' | Whether to use grouping separators |
notation? | 'standard' | 'scientific' | 'engineering' | 'compact' | Number notation format |
compactDisplay? | 'short' | 'long' | Compact notation display style |
signDisplay? | 'auto' | 'never' | 'always' | 'exceptZero' | When to display the sign |
roundingMode? | 'ceil' | 'floor' | 'expand' | 'trunc' | 'halfCeil' | 'halfFloor' | 'halfExpand' | 'halfTrunc' | 'halfEven' | Rounding mode |
roundingIncrement? | 1 | 2 | 5 | 10 | 20 | 25 | 50 | 100 | Rounding increment |
trailingZeroDisplay? | 'auto' | 'stripIfInteger' | Whether to display trailing zeroes |
Returns
string - The formatted number in line with locale conventions.
Examples
Basic number formatting
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"Currency formatting
// US Dollar formatting (US English)
console.log(gt.formatNum(1234.56, {
style: 'currency',
currency: 'USD'
}));
// Output: "$1,234.56"
// Euro formatting with the 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 (brackets for negatives)
console.log(gt.formatNum(-1234.56, {
style: 'currency',
currency: 'USD',
currencySign: 'accounting'
}));
// Output: "($1,234.56)"Percentages 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
- Number formatting automatically follows locale-specific conventions
- The method uses the browser-native
Intl.NumberFormatfor optimal performance and accuracy - Currency formatting requires both
style: 'currency'and a validcurrencycode - Unit formatting requires both
style: 'unit'and a validunitidentifier
Next steps
- Check out
Intl.NumberFormatdocumentation for more options - See
format-currencyfor specialised currency formatting - See
format-messagefor message formatting with number interpolation - See standalone
format-numfor use without a GT instance - See
get-locale-propertiesfor locale-specific formatting information
How is this guide?