Skip to main content

Intl.NumberFormat (ESNext)

A polyfill for ESNext Intl.NumberFormat and Number.prototype.toLocaleString.

npm Version size

Installation#

npm i @formatjs/intl-numberformat

Requirements#

This package requires the following capabilities:

Features#

Everything in the ES2020 Internationalization API spec (https://tc39.es/ecma402).

Usage#

Via polyfill.io#

You can use polyfill.io URL Builder to create a polyfill script tag for Intl.NumberFormat. By default the created URL does not come with any locale data. In order to add locale data, append Intl.NumberFormat.~locale.<locale>, as well as locale data for any required polyfills, to your list of features. For example:

<!-- Polyfill Intl.NumberFormat, its dependencies & `en` locale data --><script src="https://polyfill.io/v3/polyfill.min.js?features=Intl.NumberFormat,Intl.NumberFormat.~locale.en"></script>

Or if Intl.PluralRules needs to be polyfilled as well:

<!-- Polyfill Intl.NumberFormat, its dependencies & `en` locale data --><script src="https://polyfill.io/v3/polyfill.min.js?features=Intl.NumberFormat,Intl.NumberFormat.~locale.en,Intl.PluralRules.~locale.en"></script>

Simple#

import '@formatjs/intl-numberformat/polyfill'import '@formatjs/intl-numberformat/locale-data/en' // locale-data for en

Dynamic import + capability detection#

import {shouldPolyfill} from '@formatjs/intl-numberformat/should-polyfill'async function polyfill(locale: string) {  if (!shouldPolyfill(locale)) {    return  }  // Load the polyfill 1st BEFORE loading data  await import('@formatjs/intl-numberformat/polyfill')  switch (locale) {    default:      await import('@formatjs/intl-numberformat/locale-data/en')      break    case 'fr':      await import('@formatjs/intl-numberformat/locale-data/fr')      break  }}

Supported Units#

Simple Units#

Currently, the spec defines a list of sanctioned units as below.

type Unit =  | 'acre'  | 'bit'  | 'byte'  | 'celsius'  | 'centimeter'  | 'day'  | 'degree'  | 'fahrenheit'  | 'fluid-ounce'  | 'foot'  | 'gallon'  | 'gigabit'  | 'gigabyte'  | 'gram'  | 'hectare'  | 'hour'  | 'inch'  | 'kilobit'  | 'kilobyte'  | 'kilogram'  | 'kilometer'  | 'liter'  | 'megabit'  | 'megabyte'  | 'meter'  | 'mile'  | 'mile-scandinavian'  | 'millimeter'  | 'milliliter'  | 'millisecond'  | 'minute'  | 'month'  | 'ounce'  | 'percent'  | 'petabyte'  | 'pound'  | 'second'  | 'stone'  | 'terabit'  | 'terabyte'  | 'week'  | 'yard'  | 'year'

Compound Units#

You can specify X-per-Y unit, where X and Y are sanctioned simple units (e.g. kilometer-per-hour). The library will choose the best-fit localized pattern to format this compound unit.