Numeral.js

A javascript library for formatting and manipulating numbers.

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