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. 👍

License

MIT © Thiago Delgado Pinto