Needle-Pinpointing Machine


    2.0.1 • Public • Published

    Angular Numeral.js filter

    npm Build Status

    This is an Angular.js filter that applies Numeral.js formatting.

    The latest version of this library uses Numeral.js 2.x branch. There are several breaking changes in Numeral.js, as well as breaking changes in this library. If you depend on Numeral.js 1.x and cannot upgrade, please use the latest 1.x release (and corresponding 1.x branch).

    Breaking Changes in 2.x

    For details on breaking changes in Numeral.js itself, please see its changelog.

    In addition, angular-numeraljs has the following breaking changes from in 1.3.0 to 2.0.0:

    • $numeraljsConfigProvider.setCurrentLanguage(lang) has been renamed to locale(locale)
    • $numeraljsConfigProvider.setDefaultFormat(format) has been renamed to defaultFormat(format)
    • $numeraljsConfigProvider.setFormat(name, formatString) has been renamed to namedFormat(name, formatString)
    • $numeraljsConfigProvider.setLanguage(lang, def) has been renamed to register('locale', name, def)

    How to Use

    1. Include Numeral.js in your project

    2. Include either the minified or non-minified javascript file from the /dist/ folder:

      <script src="angular-numeraljs.js"></script>
    3. Inject the ngNumeraljs filter into your app module:

      var myApp = angular.module('myApp', ['ngNumeraljs']);
    4. Apply the filter with the desired format string:

          {{ price | numeraljs:'$0,0.00' }}

    Advanced Usage

    You can configure ngNumeraljs during Angular's configuration phase using the $numeraljsConfigProvider:

    var app = angular.module('exampleApp', ['ngNumeraljs']);
    app.config(['$numeraljsConfigProvider', function ($numeraljsConfigProvider) {
        // place configuration here

    Numeral.js must be already loaded in the browser prior to using $numeraljsConfigProvider.

    Named Formats

    $numeraljsConfigProvider.namedFormat(name, formatString) - defines a named format which can be used in place of the format string in the filter.

    app.config(['$numeraljsConfigProvider', function ($numeraljsConfigProvider) {
        $numeraljsConfigProvider.namedFormat('currency', '$ 0,0.00');

    In markup,

        {{ price | numeraljs:'currency' }}

    Default Format

    Numeral.js defines the default format as '0,0', so this format is used if none is provided to the filter.

    $numeraljsConfigProvider.defaultFormat(format) - overrides the built-in default format.

    app.config(['$numeraljsConfigProvider', function ($numeraljsConfigProvider) {
        $numeraljsConfigProvider.defaultFormat('0.0 $');

    In markup,

        {{ price | numeraljs }}     <!-- will produce 15.5 $ -->

    Custom Locales and Formats

    $numeraljsConfigProvider.register(type, name, definition) - adds new locale or format definitions to Numeral.js. type must be either 'locale' or 'format'. For complete details, please refer to the Numeral.js documentation.

    app.config(['$numeraljsConfigProvider', function ($numeraljsConfigProvider) {
      // Register a new Locale
      $numeraljsConfigProvider.register('locale', 'de', {
        delimiters: {
          thousands: ' ',
          decimal: ','
        abbreviations: {
          thousand: 'k',
          million: 'm',
          billion: 'b',
          trillion: 't'
        ordinal: function (number) {
          return '.';
        currency: {
          symbol: ''
      // Register a new Format
      $numeraljsConfigProvider.register('format', 'percentage', {
        regexps: {
          format: /(%)/,
          unformat: /(%)/
        format: function(value, format, roundingFunction) {
          var space = numeral._.includes(format, ' %') ? ' ' : '',
          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;

    Please note that registering a new format will add new formatting functionality, e.g. adding a new character to the format string. If you want to add a short name for a specific format string, see namedFormat() above.

    See a list of available locales here: locale.

    Locales or formats can be loaded directly into Numeral.js as well, e.g. by loading the locale files after Numeral.js is loaded. Angular-numeraljs can use these locales or formats even if they are not set via this provider.

    Select Locale

    $numeraljsConfigProvider.locale(locale) - selects the current locale. The locale must be loaded either by $numeraljsConfigProvider.register() or by loading the Numeral.js locale file.

    app.config(['$numeraljsConfigProvider', function ($numeraljsConfigProvider) {

    Runtime Configuration

    It is possible to change all of the configurations at runtime by injecting $numeraljsConfig:

    app.controller('numeralExample', function ($scope, $numeraljsConfig) {

    This may be useful for websites with a language switcher, saved user preferences, etc.


    There are several examples in the example/ folder which can be used for reference:

    • Simple: using this library in the most basic way possible
    • Config: using $numeraljsConfigProvider to configure this library
    • ChangingLanguages: changing languages (or other properties) at runtime (vs initialization)
    • Bower: adding a dependency through Bower
    • Browserify: adding a dependency through Browserify


    This filter can be installed via Bower with the following dependency in the bower.json file.

    "dependencies": {
        "angular-numeraljs": "^2.0"


    This project is published in NPM as angular-numeraljs.

    "dependencies": {
        "angular-numeraljs": "^2.0"

    The example/browserify folder has a working example with Browserify and Grunt. To build this project, install Grunt and Browserify and run the following:

    cd example/browserify
    npm install
    grunt build

    Then open example/browserify/dist/index.html in a browser.


    1. Install Grunt CLI and Node.js

    2. Install Node packages

       npm install
    3. Build via Grunt

       grunt build

      The /dist/ folder contains the regular and minified Javascript files.

    4. Tests are automatically run during the build, but they can be run manually as well

       grunt test




    npm i angular-numeraljs

    DownloadsWeekly Downloads






    Last publish


    • baumandm