Angular Numeral.js filter
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 tolocale(locale)$numeraljsConfigProvider.setDefaultFormat(format)has been renamed todefaultFormat(format)$numeraljsConfigProvider.setFormat(name, formatString)has been renamed tonamedFormat(name, formatString)$numeraljsConfigProvider.setLanguage(lang, def)has been renamed toregister('locale', name, def)
How to Use
Include Numeral.js in your project
Include either the minified or non-minified javascript file from the
/dist/folder:<script src="angular-numeraljs.js"></script>Inject the
ngNumeraljsfilter into your app module:var myApp = angular.module('myApp', ['ngNumeraljs']);Apply the filter with the desired format string:
<p> {{ price | numeraljs:'$0,0.00' }} </p>
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,
<p>
{{ price | numeraljs:'currency' }}
</p>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,
<p>
{{ price | numeraljs }} <!-- will produce 15.5 $ -->
</p>
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, ' %') ? ' ' : '',
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;
}
});
$numeraljsConfigProvider.defaultFormat('0%');
$numeraljsConfigProvider.locale('de');
}]);
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) {
$numeraljsConfigProvider.locale('de');
}]);
Runtime Configuration
It is possible to change all of the configurations at runtime by injecting $numeraljsConfig:
app.controller('numeralExample', function ($scope, $numeraljsConfig) {
$numeraljsConfig.defaultFormat('0,0.0');
$numeraljsConfig.locale($scope.locale);
});
This may be useful for websites with a language switcher, saved user preferences, etc.
Examples
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
Bower
This filter can be installed via Bower with the following dependency in the bower.json file.
"dependencies": {
"angular-numeraljs": "^2.0"
}
Browserify
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.
Building
);
}]);In markup,
__CODE_BLOCK_7__Custom Locales and Formats
__INLINE_CODE_15__ - adds new locale or format definitions to Numeral.js. __INLINE_CODE_16__ must be either __INLINE_CODE_17__ or __INLINE_CODE_18__. For complete details, please refer to the Numeral.js documentation.
__CODE_BLOCK_8__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 __INLINE_CODE_19__ 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
__INLINE_CODE_20__ - selects the current locale. The locale must be loaded either by __INLINE_CODE_21__ or by loading the Numeral.js locale file.
__CODE_BLOCK_9__Runtime Configuration
It is possible to change all of the configurations at runtime by injecting __INLINE_CODE_22__:
__CODE_BLOCK_10__This may be useful for websites with a language switcher, saved user preferences, etc.
Examples
There are several examples in the __INLINE_CODE_23__ 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
Bower
This filter can be installed via Bower with the following dependency in the __INLINE_CODE_24__ file.
__CODE_BLOCK_11__Browserify
This project is published in NPM as __INLINE_CODE_25__.
__CODE_BLOCK_12__The __INLINE_CODE_26__ folder has a working example with Browserify and Grunt. To build this project, install Grunt and Browserify and run the following:
__CODE_BLOCK_13__Then open __INLINE_CODE_27__ in a browser.