GT ClassMethodsFormatting

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

NameTypeDescription
numbernumberThe number to format
options?NumberFormatOptionsOptional formatting settings

NumberFormatOptions

Extends Intl.NumberFormatOptions with additional locale specification:

NameTypeDescription
locales?string | string[]Override locales for formatting (defaults to instance locales)
style?'decimal' | 'currency' | 'percent' | 'unit'Number formatting style
currency?stringCurrency code (required when style is 'currency')
currencyDisplay?'symbol' | 'narrowSymbol' | 'code' | 'name'How to display the currency
currencySign?'standard' | 'accounting'Currency sign to use
unit?stringUnit identifier (required when style is 'unit')
unitDisplay?'short' | 'narrow' | 'long'How to display the unit
minimumIntegerDigits?numberMinimum number of integer digits (1–21)
minimumFractionDigits?numberMinimum number of fraction digits (0–20)
maximumFractionDigits?numberMaximum number of fraction digits (0–20)
minimumSignificantDigits?numberMinimum significant digits (1–21)
maximumSignificantDigits?numberMaximum 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 | 100Rounding 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.NumberFormat for optimal 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

Next steps

How is this guide?

formatNum