Use it
In the Browser
<script src="numeral.min.js"></script>or include from cdnjs.com
<script src="//cdnjs.cloudflare.com/ajax/libs/numeral.js/2.0.6/numeral.min.js"></script>
In Node.js
npm install numeral
var numeral = require('numeral');
Create
Create an instance of a numeral. Numeral takes numbers or strings that it trys to convert into a number.
var myNumeral = numeral(1000);
var value = myNumeral.value();
// 1000
var myNumeral2 = numeral('1,000');
var value2 = myNumeral2.value();
// 1000
| Input | Value |
|---|---|
| numeral(974) | 974 |
| numeral(0.12345) | 0.12345 |
| numeral('10,000.12') | 10000.12 |
| numeral('23rd') | 23 |
| numeral('$10,000.00') | 10000 |
| numeral('100B') | 100 |
| numeral('3.467TB') | 3467000000000 |
| numeral('-76%') | -0.76 |
| numeral('2:23:57') | NaN |
Format
Numbers can be formatted to look like currency, percentages, times, or even plain old numbers with decimal places, thousands, and abbreviations. And you can always create a custom format.
var string = numeral(1000).format('0,0');
// '1,000'
Numbers
| Number | Format | String |
|---|---|---|
| 10000 | '0,0.0000' | 10,000.0000 |
| 10000.23 | '0,0' | 10,000 |
| 10000.23 | '+0,0' | +10,000 |
| -10000 | '0,0.0' | -10,000.0 |
| 10000.1234 | '0.000' | 10000.123 |
| 100.1234 | '00000' | 00100 |
| 1000.1234 | '000000,0' | 001,000 |
| 10 | '000.00' | 010.00 |
| 10000.1234 | '0[.]00000' | 10000.12340 |
| -10000 | '(0,0.0000)' | (10,000.0000) |
| -0.23 | '.00' | -.23 |
| -0.23 | '(.00)' | (.23) |
| 0.23 | '0.00000' | 0.23000 |
| 0.23 | '0.0[0000]' | 0.23 |
| 1230974 | '0.0a' | 1.2m |
| 1460 | '0 a' | 1 k |
| -104000 | '0a' | -104k |
| 1 | '0o' | 1st |
| 100 | '0o' | 100th |
Currency
| Number | Format | String |
|---|---|---|
| 1000.234 | '$0,0.00' | $1,000.23 |
| 1000.2 | '0,0[.]00 $' | 1,000.20 $ |
| 1001 | '$ 0,0[.]00' | $ 1,001 |
| -1000.234 | '($0,0)' | ($1,000) |
| -1000.234 | '$0.00' | -$1000.23 |
| 1230974 | '($ 0.00 a)' | $ 1.23 m |
Bytes
| Number | Format | String |
|---|---|---|
| 100 | '0b' | 100B |
| 1024 | '0b' | 1KB |
| 2048 | '0 ib' | 2 KiB |
| 3072 | '0.0 b' | 3.1 KB |
| 7884486213 | '0.00b' | 7.88GB |
| 3467479682787 | '0.000 ib' | 3.154 TiB |
Percentages
| Number | Format | String |
|---|---|---|
| 1 | '0%' | 100% |
| 0.974878234 | '0.000%' | 97.488% |
| -0.43 | '0 %' | -43 % |
| 0.43 | '(0.000 %)' | 43.000 % |
Time
| Number | Format | String |
|---|---|---|
| 25 | '00:00:00' | 0:00:25 |
| 238 | '00:00:00' | 0:03:58 |
| 63846 | '00:00:00' | 17:44:06 |
Exponential
| Number | Format | String |
|---|---|---|
| 1123456789 | '0,0e+0' | 1e+9 |
| 12398734.202 | '0.00e+0' | 1.24e+7 |
| 0.000123987 | '0.000e+0' | 1.240e-4 |
Functions
Value
The value is always available.
var number = numeral(1000);
var string = number.format('0,0');
// '1,000'
var value = number.value();
// 1000
Manipulate
Not that you will use these often, but they're there when you need them.
var number = numeral(1000); var added = number.add(10); // 1010
| Before | Function | After |
|---|---|---|
| 1000 | .add(100) | 1100 |
| 1100 | .subtract(100) | 1000 |
| 1000 | .multiply(100) | 100000 |
| 100000 | .divide(100) | 1000 |
Set
Set the value of your numeral object.
var number = numeral(); number.set(1000); var value = number.value(); // 1000
Difference
Find the difference between your numeral object and a value
var number = numeral(1000),
value = 100;
var difference = number.difference(value);
// 900
Clone
Go ahead and clone any numeral object while you're at it.
var a = numeral(1000); var b = numeral(a); var c = a.clone(); var aVal = a.set(2000).value(); // 2000 var bVal = b.value(); // 1000 var cVal = c.add(10).value(); // 1010
Settings
Default Formatting
Set a default format so you can use .format() without a string. The default format to '0,0'
var number = numeral(1000);
number.format();
// '1,000'
numeral.defaultFormat('$0,0.00');
number.format();
// '$1,000.00'
Custom Zero and Null Formatting
Set a custom output when formatting numerals with a value of 0 or null
var number = numeral(0);
var nullNumber = numeral(null);
numeral.zeroFormat('N/A');
numeral.nullFormat('N/A');
var zero = number.format('0.0')
// 'N/A'
var na = nullNumber.format('0.0')
// 'N/A'
Locales
Let's make this useable all over the place!
// load a locale
numeral.register('locale', 'fr', {
delimiters: {
thousands: ' ',
decimal: ','
},
abbreviations: {
thousand: 'k',
million: 'm',
billion: 'b',
trillion: 't'
},
ordinal : function (number) {
return number === 1 ? 'er' : 'ème';
},
currency: {
symbol: '€'
}
});
// switch between locales
numeral.locale('fr');
As I am not fluent in every locale on the planet, please feel free to create locale files of your own by submitting a pull request. Don't forget to create both the locale file (example: locales/fr.js) and the locale test (example: tests/locales/fr.js). Thanks for helping out.
Formats
Adding your own custom formats is as easy as adding a locale.
// load a format
numeral.register('format', 'percentage', {
regexps: {
format: /(%)/,
unformat: /(%)/
},
format: function(value, format, roundingFunction) {
var space = numeral._.includes(format, ' %') ? ' ' : '',
output;
value = value * 100;
// check for space before %
format = format.replace(/s?\%/, '');
output = numeral._.numberToFormat(value, format, roundingFunction);
if (numeral._.includes(output, ')')) {
output = output.split('');
output.splice(-1, 0, space + '%');
output = output.join('');
} else {
output = output + space + '%';
}
return output;
},
unformat: function(string) {
return numeral._.stringToNumber(string) * 0.01;
}
});
// use your custom format
numeral().format('0%');
Acknowlegements
Numeral.js, while less complex, was inspired by and heavily borrowed from Moment.js