Format

How to format numbers, currencies, etc, and unformat them.

Format

Numbers can be formatted to look like currency, percentages, times, or even plain old numbers with decimal places, thousands, and abbreviations.

var string = numbro(1000).format('0,0');
// '1,000'
	

Numbers

Number Format String
10000 '0,0.0000'
10000.23 '0,0'
10000.23 '+0,0'
-10000 '0,0.0'
10000.1234 '0.000'
10000.1234 '0[.]00000'
-10000 '(0,0.0000)'
-0.23 '.00'
-0.23 '(.00)'
0.23 '0.00000'
0.23 '0.0[0000]'
1230974 '0.0a'
1460 '0 a'
-104000 '0a'
233434 '0a.00'
233000 '0a.00'
1 '0o'
52 '0o'
23 '0o'
100 '0o'

Average

numbro provides an easy mechanism to round up any number with the special formatting character a. Note that the delimiters are per language.

Number Format String
123 '0a'
1234 '0a'
12345 '0a'
123456 '0a'
1234567 '0a'
12345678 '0a'
123456789 '0a'

In addition to this, when numbers are rounded up, one can specify the precision wanted with a format like 3a (for 3 numbers only). In this case, 0 is used for "automatic" mode.

Number Format String
1234567891 '0a'
1234567891 '1a'
1234567891 '2a'
1234567891 '3a'
1234567891 '4a'
1234567891 '5a'
1234567891 '6a'
1234567891 '7a'
1234567891 '8a'
1234567891 '9a'
1234567891 '10a'

Currency

numbro supports cultural currency formatting via the function formatCurrency.

numbro(1000.234).formatCurrency();
// $1000
		
Number Language String
1000.234 en-US
1000.234 fr-FR
1000.234 ja-JP
1000.234 ru-RU

You can of course precise a more specific format, as long as you do not use the $ (that would override defaults).

numbro(1000.234).formatCurrency("0[.]00");
// $1000.23
		
Number Language String
1000.234 en-US
1000.234 fr-FR
1000.234 ja-JP
1000.234 ru-RU

But if you want to, you can always precise a format by hand to override the languages defaults.

Number Format String
1000.234 '$0,0.00'
1000.2 '0,0[.]00 $'
1001 '$ 0,0[.]00'
-1000.234 '($0,0)'
-1000.234 '$0.00'
1230974 '($ 0.00 a)'

Note that you can set the default format for currency formatting using the function numbro.defaultCurrencyFormat. The current culture defaults are kept (symbol, symbol position, etc).

numbro.defaultCurrencyFormat('0,0[.]00');
numbro(12345678).formatCurrency();
// "$12,345,678"

numbro.language('fr-FR');
numbro(12345678).formatCurrency();
// "12,345,678 €"
		

You can even round the result with your own rounding function (default is Math.round).

numbro(1000.234).formatCurrency("", Math.ceil);
//$1001

numbro(1000.234).formatCurrency("", Math.floor);
//$1000
		

Bytes

Number Format String
100 '0b'
2048 '0 b'
7884486213 '0.0b'
3467479682787 '0.000 b'

Percentages

Number Format String
1 '0%'
0.974878234 '0.000%'
-0.43 '0 %'
0.43 '(0.000 %)'

Time

Number Format String
25 '00:00:00'
238 '00:00:00'
63846 '00:00:00'

If you want to format time more than that, we recommend you Momentjs which inspired numbro.

Unformat

Got a formatted string? Use the unformat function to make it useful again.

var string = numbro().unformat('($10,000.00)');
// -10000
	
String Function Number
'10,000.123' .unformat('10,000.123')
'0.12345' .unformat('0.12345')
'1.23m' .unformat('1.23m')
'23rd' .unformat('23rd')
'$10,000.00' .unformat('$10,000.00')
'100B' .unformat('100B')
'3.154TB' .unformat('3.154TB')
'-76%' .unformat('-76%')
'2:23:57' .unformat('2:23:57')

Defaults

numbro allows you to the default format to use, as well as how to format 0.

Default format

Set a default format so you can use .format() without a string. The default format to '0,0'.

var number = numbro(1000);

number.format();
// '1,000'

numbro.defaultFormat('$0,0.00');

number.format();
// '$1,000.00'
		

Default zero

Set a custom output when formatting numbers with a value of 0.

var number = numbro(0);

numbro.zeroFormat('N/A');

var zero = number.format('0.0')
// 'N/A'