Why

JS provides powerful number formatting with the standard built-in object Intl.NumberFormat, but we find its API a little verbose and hard to grasp its full potential. We took inspiration from older libraries like numbro.js and numeral.js and built a string based pattern for interacting with Intl.NumberFormat. Tiny footprint, no dependencies, works on the browser or nodejs.

Usage

import nf from '@tuplo/numberfmt';

// numeric
nf(123_456, '0,0.00'); // → 123,456.00

// currency
nf(123_456, '0,0GBP'); // → £123,456

// digital units
nf(123_456, '0b'); // → 120.56kb

// with locale
nf(123_456, '0,0.00', { locale: 'ar-EG' }); // → ١٢٣٬٤٥٦٫٧٩

// functional programming, partial application
const nfp = nf.partial('0,0.00');
nfp(123_456); // → 123,456.00

Install

$ npm install @tuplo/numberfmt

# or with yarn
$ yarn add @tuplo/numberfmt

Options

An optional set of options can be provided

nf(123_456, '0,0.00', { 
  locale: 'ar-EG',
  numberingSystem: 'arab'
}); // → ١٢٣٬٤٥٦٫٧٩

locale

string | optional | defaults to system locale

The BCP 47 language tag for the locale actually used.

numberingSystem

string | optional | derives from locale

Examples: arab, fullwide, hant, latn.

Reference

| Character | Meaning | | | --------- | -------------------------------- | ---------------- | | 0 | digit | 1 | | . | decimal separator | 1.2 | | , | thousands group separator | 1,234 | | [] | optional | | | - | negative sign | -1 | | () | negative sign (accounting) | (123) | | % | percentage | 95% | | o | ordinals | 1st | | a | compact notation (short display) | 1K | | A | compact notation (long display) | 1 thousand | | e | exponential (scientific) | 1E4 | | E | exponential (engineering) | 100E3 | | b | bits | 1.23Mb | | B | bytes | 1.23TB | | m | length | 1.23km | | k | mass | 1.23kg | | USD | currency symbol | US$1,000 | | s | currency narrow symbol | $1,000 | | c | currency code | USD 1,000 | | n | currency name | 1,000 US dollars |

Numbers

| Value | Format | Result | | | ------- | ------- | -------- | --------------------------------- | | 123456 | 0,0 | 123,456 | thousands separator | | 1234.5 | 0,0.0 | 1,234.5 | decimal separator | | 1234.5 | 0,0.00 | 1,234.50 | fixed number of decimal digits | | 123 | 0[.]0 | 123 | optional decimal separator | | 123.4 | 0[.]0 | 123.4 | | | 123.4 | 0[.]00 | 123.40 | | | 123.45 | 0.00[0] | 123.45 | fixed and optional decimal digits | | 123.456 | 0.00[0] | 123.456 | | | -1 | -0 | -1 | negative sign | | 1 | (0) | 1 | negative sign (accounting) | | -1 | (0) | (1) | |

Percentage

| Value | Format | Result | | ------- | ------ | ------ | | 1 | 0% | 100% | | -0.12 | 0% | -12% | | 0.12345 | 0.00% | 12.34% |

Ordinals

| Value | Format | Result | | ----- | ------ | ------- | | 0 | 0o | 0th | | 1 | 0o | 1st | | 2 | 0o | 2nd | | 3 | 0o | 3rd | | 4 | 0o | 4th | | 1234 | 0,0o | 1,234th |

Compact notation

| Value | Format | Result | | | ------------- | ------ | ----------- | ----------------------------- | | 123 | 0a | 123 | short display | | 1234 | 0a | 1K | | | 12345 | 0a | 12K | | | 123456 | 0a | 123K | | | 1234567 | 0a | 1M | | | 1234567890 | 0a | 1B | | | 1234567890123 | 0a | 1T | | | 1234 | 0A | 1 thousand | long display | | 1234567 | 0A | 1 million | | | 1234567890 | 0A | 1 billion | | | 1234567890123 | 0A | 1 trillion | | | 1234567 | 0.0a | 1.2M | combined with numeric formats | | 1234567 | 0.0A | 1.2 million | |

Exponential

| Value | Format | Result | | | -------- | ------ | ------ | ----------------------------------------------------- | | 1 | 0e | 1E0 | scientific (order-of-magnitude) | | 10 | 0e | 1E1 | | | 100 | 0e | 1E2 | | | 1000 | 0e | 1E3 | | | 10000 | 0e | 1E4 | | | 1 | 0E | 1E0 | engineering (exponent of ten when divisible by three) | | 10 | 0E | 10E0 | | | 100 | 0E | 100E0 | | | 1000 | 0E | 1E3 | | | 10000 | 0E | 10E3 | | | 100000 | 0E | 100E3 | | | 12345678 | 0.0e | 1.2E7 | combined with numeric formats | | 12345678 | 0.0E | 12.3E6 | |

Digital

| Value | Format | Result | | | ------------- | ------ | ------ | ----------------- | | 1 | 0b | 1bit | bits (narrow) | | 1024 | 0b | 1kb | | | 1048576 | 0b | 1Mb | | | 1073741824 | 0b | 1Gb | | | 1099511627776 | 0b | 1Tb | | | 1 | 0B | 1B | bytes (narrow) | | 1024 | 0B | 1kB | | | 1048576 | 0B | 1MB | | | 1073741824 | 0B | 1GB | | | 1099511627776 | 0B | 1TB | | | 1 | 0 b | 1 bit | bits (short) | | 1024 | 0 b | 1 kb | | | 1 | 0 B | 1 byte | bytes (short) | | 1024 | 0 B | 1 kB | | | 1524 | 0b | 1.49kb | 2 fraction digits | | 1524 | 0B | 1.49kB | |

Length

| Value | Format | Result | | | ----- | ------ | ------ | --------------------------------------------------- | | 0.001 | 0m | 1mm | value in meters, formatted to closest unit (narrow) | | 0.01 | 0m | 1cm | | | 1 | 0m | 1m | | | 1000 | 0m | 1km | | | 1200 | 0m | 1.2km | | | 0.001 | 0 m | 1 mm | (short) | | 0.01 | 0 m | 1 cm | | | 1 | 0 m | 1 m | | | 1000 | 0 m | 1 km | | | 1200 | 0 m | 1.2 km | |

Mass

| Value | Format | Result | | | ----- | ------ | ------- | ------ | | 1 | 0k | 1kg | narrow | | 0.001 | 0k | 1g | | | 1.23 | 0k | 1.23kg | | | 1 | 0 k | 1 kg | short | | 0.001 | 0 k | 1 g | | | 1.23 | 0 k | 1.23 kg | |

Currency

| Value | Format | Result | | | ----- | --------- | -------------------- | ----------------- | | 123 | GBP | £123 | symbol | | 1234 | 0,0GBP | £1,234 | | | 1234 | 0,0.00GBP | £1,234.00 | | | 123 | EUR | €123 | | | 123 | JPY | JP¥123 | | | 123 | USD | US$123 | | | 123 | CAD | CA$123 | | | 1000 | 0,0GBPs | £1,000 | narrow symbol | | 1000 | 0,0EURs | €1,000 | | | 1000 | 0,0USDs | $1,000 | | | 1000 | 0,0CADs | $1,000 | | | 1000 | 0,0JPYs | ¥1,000 | | | 1000 | 0,0GBPc | GBP 1,000 | ISO currency code | | 1000 | 0,0EURc | EUR 1,000 | | | 1000 | 0,0USDc | USD 1,000 | | | 1000 | 0,0JPYc | JPY 1,000 | | | 1000 | 0,0GBPn | 1,000 British pounds | currency name | | 1000 | 0,0EURn | 1,000 euros | | | 1000 | 0,0USDn | 1,000 US dollars | | | 1000 | 0,0JPYn | 1,000 Japanese yen | |

License

MIT