Intl.NumberFormat (ESNext)

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

Installation

npm

npm i @formatjs/intl-numberformat

yarn

yarn add @formatjs/intl-numberformat

Requirements

This package requires the following capabilities:

• Intl.getCanonicalLocales or polyfill
• Intl.Locale or polyfill.
• Intl.PluralRules or polyfill.

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()) {

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.