intl-number-helper

💰 Configure EcmaScript's Intl.NumberFormat with a string pattern

Instead of using something like this:

const options = { style: 'currency', currencyDisplay: 'symbol', currency: 'USD' };
const numberStr = new Intl.NumberFormat( 'en-US', options ).format( 123456 );

Use formatNumber:

const numberStr = formatNumber( 123456, 'en-US', '$' ); // Guesses the currency code

✨The function formatNumber uses Intl.NumberFormat internally and guesses the currency code (ISO 4247) from the country code (ISO 3166-1 alpha-2).

Installation

npm i intl-number-helper

Notes:

It does not polyfill Intl.NumberFormat (you can use your own polyfill if you need it).
Use it in the browser, NodeJS or DenoJS, with JavaScript 5+ and TypeScript.
Unit-tested.
Semantic Versioning.

Some polyfills for Intl.NumberFormat:

@formatjs/intl-numberformat - Browsers and NodeJS (recommended)
Intl.js - Browsers and NodeJS

Although NodeJS offers support to Intl.NumberFormat from version 10, a polyfill like formatjs' is recommended, since it is more complete and correct.

Examples

ESM, NodeJS

import { formatNumber } from 'intl-number-helper';

// US$123,456.00
console.log( formatNumber( 123456, 'en-US', '$' ) );

// R$ 123.456,00
console.log( formatNumber( 123456, 'pt-BR', '$7.2' ) );

// 123,456.00 American dollars
console.log( formatNumber( 123456, 'en-US', 'n' ) );

// 123,456.00
console.log( formatNumber( 123456, 'en-US', 'd.2' ) );

// 123,456
console.log( formatNumber( 123456, 'en-US', 'd' ) );

// 123456
console.log( formatNumber( 123456, 'en-US', 'd#' ) );

// 75%
console.log( formatNumber( 0.75, 'en-US', '%' ) );

// 100 kilometers per hour
console.log( formatNumber( 100, 'en-US', 'u',
    { unit: 'kilometer-per-hour', unitDisplay: 'long' } ) );

Browser

<script crossorigin src="https://unpkg.com/intl-number-helper" ></script>
<script>
  console.log( intlNumberHelper.formatNumber( 123456, 'en-US', 'd' ) );  // 123,456
</script>

DenoJS

// Alternatively, use an import map and include it like NodeJS
import { formatNumber } from "https://unpkg.com/intl-number-helper/index.esm.js";
console.log( formatNumber( 123456, 'en-US', 'd' ) );  // 123,456

Patterns

Pattern is symbol grouping sign integer-digits fraction-range significant-range, in this order.

Every part is optional.

symbol

Pattern example	Generated object
`'d'`	`{ style: 'decimal' }`
`'%'`	`{ style: 'percent' }`
`'u'`	`{ style: 'unit' }`
`'$'`	`{ style: 'currency', currencyDisplay: 'symbol' }`
`'w'`	`{ style: 'currency', currencyDisplay: 'narrowSymbol' }`
`'n'`	`{ style: 'currency', currencyDisplay: 'name' }`
`'o'`	`{ style: 'currency', currencyDisplay: 'code' }`
`'a'`	`{ style: 'currency', currencySign: 'accounting' }`
`'E'`	`{ notation: 'scientific' }`
`'e'`	`{ notation: 'engineering' }`
`'c'`	`{ notation: 'compact' }`
`'l'`	`{ notation: 'compact', compactDisplay: 'long' }`
`'s'`	`{ notation: 'compact', compactDisplay: 'short' }`

grouping

Pattern example	Generated object
`''`	`{}`, which is the same as `{ useGrouping: true }` (default value)
`'#'`	`{ useGrouping: false }`

sign

Pattern example	Generated object
`''` (empty)	`{}`, which is the same as `{ signDisplay: 'auto' }` (default value)
`'+'`	`{ signDisplay: 'exceptZero' }`
`'!'`	`{ signDisplay: 'never' }`
`'@'`	`{ signDisplay: 'always' }`

integer-digits

A number between 0 and 21 (inclusive).

Pattern example	Generated object
`'7'`	`{ minimumIntegerDigits: 7 }`

fraction-range

It establishes the minimum and the maximum digits for the fraction part.
It must be preceded by . and use - to separate the values (numbers).
The minimum part is always informed.
Every number must be between 1 and 20 (inclusive).

Pattern example	Generated object
`'.1'`	`{ minimumFractionDigits: 1 }`
`'.1-2'`	`{ minimumFractionDigits: 1, maximumFractionDigits: 2 }`
`'#.1-2'`	`{ useGrouping: false, minimumFractionDigits: 1, maximumFractionDigits: 2 }`

significant-range

Same as fraction-range, but preceded by ;

Pattern example	Generated object
`';1'`	`{ minimumSignificantDigits: 1 }`
`';1-2'`	`{ minimumSignificantDigits: 1, maximumSignificantDigits: 2 }`
`'#;1-2'`	`{ useGrouping: false, minimumSignificantDigits: 1, maximumSignificantDigits: 2 }`

More examples

Putting some patterns together

Pattern example	Generated object
`'$7.2-2'`	`{ style: 'currency', currencyDisplay: 'symbol', minimumIntegerDigits: 7, minimumFractionDigits: 2, maximumFractionDigits: 2 }`
`'$7.2-2;2'`	`{ style: 'currency', currencyDisplay: 'symbol', minimumIntegerDigits: 7, minimumFractionDigits: 2, maximumFractionDigits: 2, minimumSignificantDigits: 2 }`
`'$+7.2-2;1-2'`	`{ style: 'currency', currencyDisplay: 'symbol', signDisplay: 'exceptZero', minimumIntegerDigits: 7, maximumFractionDigits: 2, minimumSignificantDigits: 1, maximumSignificantDigits: 2 }`

API

/**
 * Formats a number.
 *
 * @param value Value to be formatted.
 * @param locale Locale. When `pattern` uses currency, it guesses the currency from the country code.
 * @param pattern Pattern. Optional. It generates an empty options object by default.
 * @param additionalOptions Options to be added to those generated from the pattern. Optional. Useful for units.
 *
 * @throws Error When
 */
function formatNumber(
    value: number,
    locale: string,
    pattern?: string,
    additionalOptions?: Intl.NumberFormatOptions
): string;

/**
 * Creates a `Intl.NumberFormatOptions` object from a given pattern.

 * @param pattern Pattern. Optional. It generates an empty options object by default.
 * @param additionalOptions Options to be added to those generated from the pattern. Optional. Useful for units.
 *
 * @example
 *  const options = makeOptions( '$', { currency: 'USD' } );
 *  const numberStr = new Intl.NumberFormat( 'en-US', options ).format( 123456 );
 *
 */
function makeOptions(
    pattern?: string,
    additionalOptions?: Intl.NumberFormatOptions
): Intl.NumberFormatOptions;

/**
 * Indicates if the given pattern is correct.
 *
 * @param pattern Pattern
 */
function isPatternCorrect( pattern: string ): boolean;

What's Next

Offering support to more patterns.

Suggestions? Please open an Issue. 👍

thiagodp/intl-number-helper