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 |
---|
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 |
---|
Currency
Number | Format | String |
---|
Bytes
Number | Format | String |
---|
Percentages
Number | Format | String |
---|
Time
Number | Format | String |
---|
Exponential
Number | Format | String |
---|
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 |
---|
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