JavaScript Intl.NumberFormat Guide

The Intl.NumberFormat API provides locale-aware number formatting for currencies, percentages, and more. Here's how to use it.

Basic Usage#

// Default formatting
const formatter = new Intl.NumberFormat();
console.log(formatter.format(1234567.89));  // '1,234,567.89' (US English)

// Specific locale
const deFormatter = new Intl.NumberFormat('de-DE');
console.log(deFormatter.format(1234567.89));  // '1.234.567,89'

const frFormatter = new Intl.NumberFormat('fr-FR');
console.log(frFormatter.format(1234567.89));  // '1 234 567,89'

// Multiple locales (fallback)
const formatter = new Intl.NumberFormat(['ban', 'id']);
// Uses Indonesian if Balinese not available

Currency Formatting#

// Basic currency
const usdFormatter = new Intl.NumberFormat('en-US', {
  style: 'currency',
  currency: 'USD',
});
console.log(usdFormatter.format(1234.56));  // '$1,234.56'

// Different currencies
const eurFormatter = new Intl.NumberFormat('de-DE', {
  style: 'currency',
  currency: 'EUR',
});
console.log(eurFormatter.format(1234.56));  // '1.234,56 €'

const jpyFormatter = new Intl.NumberFormat('ja-JP', {
  style: 'currency',
  currency: 'JPY',
});
console.log(jpyFormatter.format(1234));  // '¥1,234'

// Currency display options
const options = {
  style: 'currency',
  currency: 'USD',
  currencyDisplay: 'code',  // 'symbol' | 'narrowSymbol' | 'code' | 'name'
};

new Intl.NumberFormat('en-US', { ...options, currencyDisplay: 'symbol' })
  .format(1234);  // '$1,234.00'
new Intl.NumberFormat('en-US', { ...options, currencyDisplay: 'code' })
  .format(1234);  // 'USD 1,234.00'
new Intl.NumberFormat('en-US', { ...options, currencyDisplay: 'name' })
  .format(1234);  // '1,234.00 US dollars'

Percentage Formatting#

// Basic percentage
const percentFormatter = new Intl.NumberFormat('en-US', {
  style: 'percent',
});
console.log(percentFormatter.format(0.25));  // '25%'

// With decimals
const precisePercent = new Intl.NumberFormat('en-US', {
  style: 'percent',
  minimumFractionDigits: 2,
  maximumFractionDigits: 2,
});
console.log(precisePercent.format(0.1234));  // '12.34%'

// Different locales
const dePercent = new Intl.NumberFormat('de-DE', {
  style: 'percent',
});
console.log(dePercent.format(0.25));  // '25 %'

Unit Formatting#

// Basic unit
const meterFormatter = new Intl.NumberFormat('en-US', {
  style: 'unit',
  unit: 'meter',
});
console.log(meterFormatter.format(100));  // '100 m'

// Compound units
const speedFormatter = new Intl.NumberFormat('en-US', {
  style: 'unit',
  unit: 'kilometer-per-hour',
});
console.log(speedFormatter.format(100));  // '100 km/h'

// Unit display options
const options = {
  style: 'unit',
  unit: 'liter',
};

new Intl.NumberFormat('en-US', { ...options, unitDisplay: 'short' })
  .format(5);  // '5 L'
new Intl.NumberFormat('en-US', { ...options, unitDisplay: 'long' })
  .format(5);  // '5 liters'
new Intl.NumberFormat('en-US', { ...options, unitDisplay: 'narrow' })
  .format(5);  // '5L'

// Common units
const units = [
  'byte', 'kilobyte', 'megabyte', 'gigabyte',
  'celsius', 'fahrenheit',
  'meter', 'kilometer', 'mile',
  'gram', 'kilogram', 'pound',
  'liter', 'gallon',
  'second', 'minute', 'hour', 'day',
];

Decimal Options#

// Minimum/maximum integer digits
const intFormatter = new Intl.NumberFormat('en-US', {
  minimumIntegerDigits: 4,
});
console.log(intFormatter.format(42));  // '0,042'

// Minimum/maximum fraction digits
const fractionFormatter = new Intl.NumberFormat('en-US', {
  minimumFractionDigits: 2,
  maximumFractionDigits: 4,
});
console.log(fractionFormatter.format(1.5));      // '1.50'
console.log(fractionFormatter.format(1.12345));  // '1.1235'

// Significant digits
const sigFormatter = new Intl.NumberFormat('en-US', {
  minimumSignificantDigits: 3,
  maximumSignificantDigits: 5,
});
console.log(sigFormatter.format(1.2));       // '1.20'
console.log(sigFormatter.format(12345.6));   // '12,346'

Notation Options#

// Scientific notation
const sciFormatter = new Intl.NumberFormat('en-US', {
  notation: 'scientific',
});
console.log(sciFormatter.format(1234567));  // '1.235E6'

// Engineering notation
const engFormatter = new Intl.NumberFormat('en-US', {
  notation: 'engineering',
});
console.log(engFormatter.format(1234567));  // '1.235E6'

// Compact notation (K, M, B)
const compactFormatter = new Intl.NumberFormat('en-US', {
  notation: 'compact',
});
console.log(compactFormatter.format(1234));       // '1.2K'
console.log(compactFormatter.format(1234567));    // '1.2M'
console.log(compactFormatter.format(1234567890)); // '1.2B'

// Compact with display option
const longCompact = new Intl.NumberFormat('en-US', {
  notation: 'compact',
  compactDisplay: 'long',
});
console.log(longCompact.format(1234567));  // '1.2 million'

// Compact in different locales
const jaCompact = new Intl.NumberFormat('ja-JP', {
  notation: 'compact',
});
console.log(jaCompact.format(10000));  // '1万'

Sign Display#

// Always show sign
const alwaysSign = new Intl.NumberFormat('en-US', {
  signDisplay: 'always',
});
console.log(alwaysSign.format(42));   // '+42'
console.log(alwaysSign.format(-42));  // '-42'
console.log(alwaysSign.format(0));    // '+0'

// Sign for non-zero only
const exceptZero = new Intl.NumberFormat('en-US', {
  signDisplay: 'exceptZero',
});
console.log(exceptZero.format(42));   // '+42'
console.log(exceptZero.format(-42));  // '-42'
console.log(exceptZero.format(0));    // '0'

// Accounting format for negative
const accounting = new Intl.NumberFormat('en-US', {
  style: 'currency',
  currency: 'USD',
  currencySign: 'accounting',
});
console.log(accounting.format(-42));  // '($42.00)'

Format to Parts#

// Get formatted parts as array
const formatter = new Intl.NumberFormat('en-US', {
  style: 'currency',
  currency: 'USD',
});

const parts = formatter.formatToParts(1234.56);
console.log(parts);
// [
//   { type: 'currency', value: '$' },
//   { type: 'integer', value: '1' },
//   { type: 'group', value: ',' },
//   { type: 'integer', value: '234' },
//   { type: 'decimal', value: '.' },
//   { type: 'fraction', value: '56' }
// ]

// Custom styling based on parts
function formatWithStyles(number, formatter) {
  return formatter.formatToParts(number).map(part => {
    switch (part.type) {
      case 'currency':
        return `<span class="currency">${part.value}</span>`;
      case 'integer':
        return `<span class="integer">${part.value}</span>`;
      case 'fraction':
        return `<span class="fraction">${part.value}</span>`;
      default:
        return part.value;
    }
  }).join('');
}

Range Formatting#

// Format number range
const rangeFormatter = new Intl.NumberFormat('en-US', {
  style: 'currency',
  currency: 'USD',
});

console.log(rangeFormatter.formatRange(100, 200));
// '$100.00 – $200.00'

// Range with compact notation
const compactRange = new Intl.NumberFormat('en-US', {
  notation: 'compact',
});
console.log(compactRange.formatRange(1000, 5000));
// '1K – 5K'

Rounding Options#

// Rounding mode
const ceilFormatter = new Intl.NumberFormat('en-US', {
  maximumFractionDigits: 2,
  roundingMode: 'ceil',
});
console.log(ceilFormatter.format(1.234));  // '1.24'

const floorFormatter = new Intl.NumberFormat('en-US', {
  maximumFractionDigits: 2,
  roundingMode: 'floor',
});
console.log(floorFormatter.format(1.236));  // '1.23'

// Rounding increment
const nickelFormatter = new Intl.NumberFormat('en-US', {
  style: 'currency',
  currency: 'USD',
  roundingIncrement: 5,
  maximumFractionDigits: 2,
});
console.log(nickelFormatter.format(1.22));  // '$1.20'
console.log(nickelFormatter.format(1.23));  // '$1.25'

Practical Examples#

// Price formatter
function formatPrice(amount, currency = 'USD', locale = 'en-US') {
  return new Intl.NumberFormat(locale, {
    style: 'currency',
    currency,
  }).format(amount);
}

// File size formatter
function formatFileSize(bytes) {
  const units = ['byte', 'kilobyte', 'megabyte', 'gigabyte', 'terabyte'];
  let unitIndex = 0;
  let size = bytes;

  while (size >= 1024 && unitIndex < units.length - 1) {
    size /= 1024;
    unitIndex++;
  }

  return new Intl.NumberFormat('en-US', {
    style: 'unit',
    unit: units[unitIndex],
    maximumFractionDigits: 2,
  }).format(size);
}

console.log(formatFileSize(1234567890));  // '1.15 GB'

// Compact number with threshold
function formatNumber(num, compact = true) {
  const options = compact && Math.abs(num) >= 1000
    ? { notation: 'compact', maximumFractionDigits: 1 }
    : { maximumFractionDigits: 0 };

  return new Intl.NumberFormat('en-US', options).format(num);
}

Caching Formatters#

// Cache formatters for performance
const formatters = new Map();

function getCurrencyFormatter(currency, locale = 'en-US') {
  const key = `${locale}-${currency}`;

  if (!formatters.has(key)) {
    formatters.set(
      key,
      new Intl.NumberFormat(locale, {
        style: 'currency',
        currency,
      })
    );
  }

  return formatters.get(key);
}

// Usage
const usd = getCurrencyFormatter('USD');
console.log(usd.format(100));  // '$100.00'

Best Practices#

Locale Handling:
✓ Use user's locale when possible
✓ Provide locale fallbacks
✓ Test with multiple locales
✓ Consider right-to-left locales

Currency:
✓ Use ISO 4217 currency codes
✓ Match locale to currency region
✓ Consider currencyDisplay option
✓ Handle accounting format

Performance:
✓ Cache formatter instances
✓ Reuse formatters
✓ Avoid creating in loops
✓ Use formatToParts for custom display

Avoid:
✗ Manual number formatting
✗ String concatenation for currency
✗ Ignoring locale differences
✗ Creating formatters repeatedly

Intl.NumberFormat provides comprehensive locale-aware number formatting for currencies, percentages, units, and general numbers. Use it instead of manual string manipulation to ensure correct formatting across different locales. Cache formatter instances for performance and use formatToParts when you need fine-grained control over the output display.