Creating a formatter

Introduction

Intl.NumberFormat formats numbers for a locale: currency, percent, units, compact notation, and grouping. Output depends on the runtime's ICU data.

Basic usage

Constructor

new Intl.NumberFormat()
new Intl.NumberFormat('en-US')
new Intl.NumberFormat('en-US', {
  maximumFractionDigits: 2
})

Formatting

const nf = new Intl.NumberFormat('en-US')

nf.format(1234567.891)  // → '1,234,567.891'
nf.format(-0.5)         // → '-0.5'

locales takes a BCP 47 tag or an array of them; unsupported tags fall back to the runtime default. The default style is 'decimal'. Output depends on the runtime's ICU data; reuse a formatter in loops.

See: Intl.NumberFormat

Options without a locale

const opts = { style: 'percent' }

new Intl.NumberFormat('default', opts).format(0.25)
// → '25%'
new Intl.NumberFormat(undefined, opts).format(0.25)
// → '25%'

'default' and undefined both mean "use the runtime's default locale".

See: locales argument

Styles

Currency

new Intl.NumberFormat('en-US', {
  style: 'currency',
  currency: 'USD'
}).format(1234.5)
// → '$1,234.50'

currency is required for this style and takes an ISO 4217 code. The default display is the locale's symbol.

See: currency

Percent

new Intl.NumberFormat('en-US', {
  style: 'percent'
}).format(0.256)
// → '26%'

percent multiplies by 100 and formats with the locale's percent sign.

See: style

Units

new Intl.NumberFormat('en-US', {
  style: 'unit',
  unit: 'kilometer-per-hour'
}).format(50)
// → '50 km/h'

Formatter

const liter = (unitDisplay) => (
  new Intl.NumberFormat('en-US', {
    style: 'unit', unit: 'liter', unitDisplay
  })
)

Display

liter('short').format(2.5)   // → '2.5 L'
liter('narrow').format(2.5)  // → '2.5L'
liter('long').format(2.5)    // → '2.5 liters'

unit takes an identifier such as liter; unitDisplay defaults to 'short'.

See: unit

Currency options

Currency display

Formatter

const usd = (currencyDisplay) => (
  new Intl.NumberFormat('en-US', {
    style: 'currency', currency: 'USD', currencyDisplay
  })
)

Output

usd('symbol').format(1234.5)        // → '$1,234.50'
usd('code').format(1234.5)          // → 'USD 1,234.50'
usd('name').format(1234.5)          // → '1,234.50 US dollars'

Narrow symbols

const cad = (currencyDisplay) => (
  new Intl.NumberFormat('en-US', {
    style: 'currency', currency: 'CAD', currencyDisplay
  })
)

cad('symbol').format(1234.5)        // → 'CA$1,234.50'
cad('narrowSymbol').format(1234.5)  // → '$1,234.50'

narrowSymbol drops the country prefix, code prints the ISO code, and name spells the currency out with the locale's plural rules.

See: currencyDisplay

Accounting format

new Intl.NumberFormat('en-US', {
  style: 'currency',
  currency: 'USD',
  currencySign: 'accounting'
}).format(-1234.5)
// → '($1,234.50)'

'standard' (the default) writes -$1,234.50; 'accounting' wraps negatives in parentheses where the locale does.

See: currencySign

Notation

Compact notation

Formatter

const compact = new Intl.NumberFormat('en-US', {
  notation: 'compact'
})

Output

compact.format(1234)      // → '1.2K'
compact.format(1500)      // → '1.5K'
compact.format(2000000)   // → '2M'

Long display

new Intl.NumberFormat('en-US', {
  notation: 'compact',
  compactDisplay: 'long'
}).format(2000000)
// → '2 million'

compactDisplay defaults to 'short'. Compact notation rounds by significant digits unless fraction digits are set.

See: notation

Scientific and engineering

new Intl.NumberFormat('en-US', {
  notation: 'scientific'
}).format(987654321)  // → '9.877E8'

new Intl.NumberFormat('en-US', {
  notation: 'engineering'
}).format(987654321)  // → '987.654E6'

scientific prints one leading digit; engineering groups the exponent in threes.

See: notation

Digits and rounding

Fraction digits

Formatter

const fraction = (options) => (
  new Intl.NumberFormat('en-US', options)
)

Output

fraction({ minimumFractionDigits: 2 }).format(42)
// → '42.00'
fraction({ maximumFractionDigits: 0 }).format(42.666)
// → '43'

Decimal numbers default to minimumFractionDigits: 0 and maximumFractionDigits: 3; currency defaults use the currency's minor unit.

See: minimumFractionDigits

Significant digits

Formatter

const sig = (options) => (
  new Intl.NumberFormat('en-US', options)
)

Output

sig({ maximumSignificantDigits: 3 }).format(1234.5)
// → '1,230'
sig({ minimumSignificantDigits: 5 }).format(1.5)
// → '1.5000'

Significant digits win over fraction digits unless roundingPriority says otherwise.

See: maximumSignificantDigits

Rounding

Rounding mode

const floor = new Intl.NumberFormat('en-US', {
  maximumFractionDigits: 0,
  roundingMode: 'floor'
})

floor.format(1.9)  // → '1'

Trailing zeros

const strip = new Intl.NumberFormat('en-US', {
  minimumFractionDigits: 2,
  trailingZeroDisplay: 'stripIfInteger'
})

strip.format(1)    // → '1'
strip.format(1.5)  // → '1.50'

roundingMode defaults to 'halfExpand'; other values include 'ceil', 'floor', 'trunc', and 'halfEven'. stripIfInteger hides all-zero fractions but keeps real decimals.

See: roundingMode

Signs and grouping

Sign display

Formatter

const sign = (signDisplay) => (
  new Intl.NumberFormat('en-US', { signDisplay })
)

Output

sign('always').format(42)      // → '+42'
sign('exceptZero').format(0)   // → '0'
sign('never').format(-42)      // → '42'

'auto' (the default) signs negatives only; 'negative' also hides negative zero.

See: signDisplay

Grouping

Formatter

const enUS = (options) => (
  new Intl.NumberFormat('en-US', options)
)

Output

enUS({ useGrouping: false }).format(1234567)  // → '1234567'
enUS({ useGrouping: 'min2' }).format(999)     // → '999'
enUS({ useGrouping: 'min2' }).format(12345)   // → '12,345'

'auto' is the default; 'min2' groups only when a group holds two or more digits. Indian English groups differently (12,34,567).

See: useGrouping

Inspecting output

formatToParts()

Formatter

const nf = new Intl.NumberFormat('en-US', {
  style: 'currency',
  currency: 'USD'
})

Parts

nf.formatToParts(1234.5)
// → [{ type: 'currency', value: '$' },
//    { type: 'integer', value: '1' },
//    { type: 'group', value: ',' },
//    ...]

Part types

TypeExample
currency$
integer1, 234
group,
decimal.
fraction50
literal' – '
minusSign-
plusSign+
percentSign%
unitkm/h
exponentSeparatorE
exponentInteger3
compactK
nanNaN

Joining every value reproduces format(). Use the parts to style digits or insert markup.

See: formatToParts()

formatRange()

Formatter

const usd = new Intl.NumberFormat('en-US', {
  style: 'currency',
  currency: 'USD',
  maximumFractionDigits: 0
})

Output

usd.formatRange(3, 5)      // → '$3 – $5'
usd.formatRange(2.9, 3.1)  // → '~$3'

formatRangeToParts() adds a source of startRange, endRange, or shared. Both need Chrome 106+, Firefox 116+, Safari 15.4+, or Node 19+.

See: formatRange()

resolvedOptions()

Formatter

const nf = new Intl.NumberFormat('de-DE', {
  style: 'unit',
  unit: 'kilometer'
})

Output

nf.resolvedOptions().locale       // → 'de-DE'
nf.resolvedOptions().unit         // → 'kilometer'
nf.resolvedOptions().unitDisplay  // → 'short'

resolvedOptions() returns the locale and every option after defaults apply.

See: resolvedOptions()

Locales

Locale differences

LocalePlain numberLocal currency
en-US1,234,567.891$1,234.50
en-GB1,234,567.891£1,234.50
de-DE1.234.567,8911.234,50 €
ja-JP1,234,567.891¥1,235
en-IN12,34,567.891₹1,234.50

Grouping, decimal marks, and symbol placement come from CLDR data, so the same code prints differently per locale.

See: locales argument

Numbering system

new Intl.NumberFormat('ar-EG').format(1234.5)
// → '١٬٢٣٤٫٥'
new Intl.NumberFormat('ar-EG', {
  numberingSystem: 'latn'
}).format(1234.5)
// → '1,234.5'

numberingSystem overrides the locale's digits; 'latn' is Western, 'arab' Arabic-Indic, and 'hanidec' Chinese numerals.

See: numberingSystem

toLocaleString()

(1234.5).toLocaleString('en-US', {
  style: 'currency',
  currency: 'USD'
})
// → '$1,234.50'

toLocaleString() is equivalent to new Intl.NumberFormat(locale, options).format(number), but builds a formatter per call.

See: toLocaleString()

Options reference

Combined example

Formatter

const nf = new Intl.NumberFormat('en-US', {
  style: 'currency',
  currency: 'USD',
  currencyDisplay: 'narrowSymbol',
  signDisplay: 'always',
  maximumFractionDigits: 0
})

Output

nf.format(1234.5)  // → '+$1,235'

The options below combine into the formatter above.

See: Intl.NumberFormat options

Style options

OptionValues
style'decimal' (default), 'currency', 'percent', 'unit'
currencyISO 4217 code; required for 'currency'
currencyDisplay'symbol' (default), 'narrowSymbol', 'code', 'name'
currencySign'standard' (default), 'accounting'
unite.g. 'liter'; required for 'unit'
unitDisplay'short' (default), 'narrow', 'long'
notation'standard' (default), 'scientific', 'engineering', 'compact'
compactDisplay'short' (default), 'long'

See: style

Digit options

OptionValues
minimumIntegerDigits1–21 (default 1)
minimumFractionDigits0–100 (default 0; 2 for most currencies)
maximumFractionDigits0–100 (default 3; currency minor units)
minimumSignificantDigits1–21 (default 1)
maximumSignificantDigits1–21 (default 21)
roundingIncrement1 (default), 2, 5, 10, 20, 25, 50, …
roundingMode'halfExpand' (default), 'ceil', 'floor', 'expand', 'trunc', 'halfCeil', 'halfFloor', 'halfTrunc', 'halfEven'
trailingZeroDisplay'auto' (default), 'stripIfInteger'

See: minimumIntegerDigits

Other options

OptionValues
signDisplay'auto' (default), 'always', 'exceptZero', 'negative', 'never'
useGrouping'auto' (default), 'always', 'min2', false
numberingSysteme.g. 'latn', 'arab', 'hanidec'
roundingPriority'auto' (default), 'morePrecision', 'lessPrecision'
localeMatcher'best fit' (default), 'lookup'

See: signDisplay

Errors and fallbacks

new Intl.NumberFormat('en-US', { style: 'currency' })
// TypeError: Currency code is required with currency style.

new Intl.NumberFormat('en-US', {
  minimumFractionDigits: 3,
  maximumFractionDigits: 1
})
// RangeError: maximumFractionDigits value is out of range.

Missing currency or unit, invalid enums, and contradictory digit ranges throw.

See: Exceptions

0 Comments for this cheatsheet. Write yours!