README
Banknote
Banknote is a small, easy-to-use JavaScript library that provides a simple way to format monetary amounts in multiple locales and currencies. It’s mainly targeted at Node.js, but also works in the browser (if needed) with module bundlers like Webpack and Browserify.
Features
Banknote addresses a common problem faced by anyone (for example, an e-commerce company) who has to update and format prices on the frontend. It is different from similar projects in that it follows Unicode CLDR formatting standards, not an ad hoc data solution. It also:
- is customizable — you can use emoticons, preferred symbols, etc.
- allows you to override its default settings — for example, if you want to apply US formatting to amounts in Chinese yen
If you want to do more than just format monetary amounts, and you are open to changing your build process or accepting a ~300MB node module, then we recommend using jQuery Foundation’s globalize. It uses the same data as Banknote, but includes access to all of the Unicode CLDR.
How to Use
Requirements
- npm (either backend or frontend)
Examples
Single Locale
If your app only uses one locale, then the code is very straightforward:
var banknote = require('banknote');
var formattingOptions = banknote.formattingForLocale('en-US');
console.log(banknote.formatSubunitAmount(123456, formattingOptions));
// "$1,234.56"
Explicit Currency
For some applications, you’ll need a way to specify different currencies without changing number-formatting rules. Here’s an example of the “en” number-formatting rules, but with Euro:
var banknote = require('banknote');
var formattingOptions = banknote.formattingForLocale('en-US', 'EUR');
console.log(banknote.formatSubunitAmount(123456, formattingOptions));
// "€1,234.56"
Dynamic Locales
Quite often, you have to change a locale based on an incoming request or some other input. We recommended using the memoization function together with a fallback logic. For example:
var banknote = require('banknote');
var memoize = require('memoizee');
var memoizedFormattingOptions = memoize(banknote.formattingForLocale);
var defaultFormattingOptions = banknote.formattingForLocale('en-US');
// Express.js init here ...
app.get('/', function(req, res){
var locale = parseAcceptLanguageForMainLocale(req.headers['accept-language']);
var formattingOptions;
try {
formattingOptions = memoizedFormattingOptions(locale);
} catch (e) {
formattingOptions = defaultFormattingOptions;
}
res.write(banknote.formatSubunitAmount(123456, formattingOptions));
// "€1,234.56"
});
Customizing Default Formatters
With banknote
, you can also customize any of the formatting options yourself. For example:
var banknote = require('banknote');
var formattingOptions = banknote.formattingForLocale('en-US');
// disable "cents"
formattingOptions.showDecimalIfWhole = false;
// remove the thousand separator
formattingOptions.thousandSeparator = '';
formattingOptions.currencyFormatter = function (symbol, formattedNumber, minus) {
return minus + symbol + ' ' + formattedNumber;
};
console.log(banknote.formatSubunitAmount(123400, formattingOptions));
// "$1234"
We’ve noticed that many libraries lack a currencyFormatter
function to place things in their correct positions — providing separate options instead. Unfortunately, separate options won’t satisfy all possible locale settings. For example, de-CH
requires placing -
after the currency symbol, which is usually unsupported or results in an explosion of parameters.
Formatting Options
Here’s a list of all the properties in formatting options obtained from the formattingForLocale
call:
var formattingOptions = {
/**
* Controls whether the subunit (decimal) part is shown when
* the value is exact, e.g. exactly $8 and 0¢
* @type boolean
*/
showDecimalIfWhole: true,
/**
*
* @type number
*/
subunitsPerUnit: 100,
/**
* Effective locale means the exact locale that will be used
* when formatting numbers. It doesn't necessarily match the
* locale passed to `formattingForLocale()` call because
* of the fallback logic.
* @type string
*/
effectiveLocale: 'en',
/**
* Currency code is not used directly and is provided here
* for reference or custom logic for the clients of the lib
* @type string
*/
currencyCode: 'USD',
/**
* Symbol passed in to `currencyFormatter` function.
* @type string
*/
currencySymbol: '