@tuplo/numberfmt

numberfmt

Number formatting using a text pattern and native Intl.NumberFormat()

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