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.

Since version 2.0.0, formatting is done via a literal object allowing easier customization and more predictable output.

var string = numbro(1000).format({thousandSeparated: true});
// '1,000'

All available options can be found in the code directly.

Numbers

Number Format String
10000 
{
    thousandSeparated: true,
    mantissa: 4
}
10000.23 
{
    thousandSeparated: true
}
10000.23 
{
    thousandSeparated: true,
    forceSign: true
}
-10000 
{
    thousandSeparated: true,
    mantissa: 1
}
10000.1234 
{
    mantissa: 3
}
10000.1234 
{
    optionalMantissa: true,
    mantissa: 5
}
1.23 
{
    trimMantissa: true,
    mantissa: 4
}
1.234 
{
    trimMantissa: true,
    mantissa: 4
}
1.2345 
{
    trimMantissa: true,
    mantissa: 4
}
1.23456 
{
    trimMantissa: true,
    mantissa: 4
}
-10000 
{
    thousandSeparated: true,
    negative: "parenthesis",
    mantissa: 4
}
-0.23 
{
    mantissa: 2
}
-0.23 
{
    negative: "parenthesis",
    mantissa: 2
}
0.23 
{
    mantissa: 5
}
1230974 
{
    average: true,
    mantissa: 1
}
1460 
{
    spaceSeparated: true,
    average: true
}
-104000 
{
    spaceSeparated: false,
    average: true
}
233434 
{
    average: true,
    mantissa: 2,
}
233000 
{
    average: true,
    mantissa: 2,
}
1 
{
    output: "ordinal"
}
52 
{
    output: "ordinal"
}
23 
{
    output: "ordinal"
}
100 
{
    output: "ordinal"
}

Average

numbro provides an easy mechanism to round up any number with the key average. Note that the abbreviation is language-specific.

Number Format String
123 
{
    average: true
}
1234 
{
    average: true
}
12345 
{
    average: true
}
123456 
{
    average: true
}
1234567 
{
    average: true
}
12345678 
{
    average: true
}
123456789 
{
    average: true
}

In addition to this, when numbers are rounded up, one can specify the precision wanted with the key totalLength.

Number Format String
1234567891 
{
    average: true
}
1234567891 
{
    average: true,
    totalLength: 1
}
1234567891 
{
    average: true,
    totalLength: 2
}
1234567891 
{
    average: true,
    totalLength: 3
}
1234567891 
{
    average: true,
    totalLength: 4
}
1234567891 
{
    average: true,
    totalLength: 5
}
1234567891 
{
    average: true,
    totalLength: 6
}
1234567891 
{
    average: true,
    totalLength: 7
}
1234567891 
{
    average: true,
    totalLength: 8
}
1234567891 
{
    average: true,
    totalLength: 9
}
1234567891 
{
    average: true,
    totalLength: 10
}

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({ mantissa: 2 });
// $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 
{
    thousandSeparated: true,
    mantissa: 2
}
1000.2 
{
    average: true,
    mantissa: 2,
    optionalMantissa: true,
    currencyPosition: "postfix",
    spaceSeparated: true
}
1001 
{
    average: true,
    mantissa: 2,
    optionalMantissa: true,
    currencyPosition: "prefix"
}
-1000.234 
{
    thousandSeparated: true,
    negative: "parenthesis"
}
-1000.234 
{
    mantissa: 2
}
1230974 
{
    average: true,
    mantissa: 2,
    optionalMantissa: true,
    spaceSeparated: true
}

Bytes

Number Format String
100 
{
    output: "byte",
    base: "binary"
}
2048 
{
    output: "byte",
    base: "binary",
    spaceSeparated: true
}
7884486213 
{
    output: "byte",
    base: "binary",
    mantissa: 1
}
3467479682787 
{
    output: "byte",
    base: "binary",
    mantissa: 3,
    spaceSeparated: true
}

Percentages

Number Format String
1 
{
    output: "percent"
}
0.974878234 
{
    output: "percent",
    mantissa: 4
}
-0.43 
{
    output: "percent",
    spaceSeparated: true
}
0.43 
{
    output: "percent",
    mantissa: 3,
    negative: "parenthesis",
    spaceSeparated: true
}

Time

Number Format String
25 
{
    output: "time"
}
238 
{
    output: "time"
}
63846 
{
    output: "time"
}

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.setDefaults({
    thousandSeparated: true,
    mantissa: 2
});

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'

Made with by Benjamin Van Ryseghem