About
CurrencyFormatter.js allows you to format numbers as currencies. It contains 155 currency definitions and 715 locale definitions out of the box. It handles unusually formatted currencies, such as the INR. This library is now used by hedge funds, banks and a variety of other organisations across the world for the efficient formatting of currencies in a wide range of applications.
This library was originally created by the Bx team while developing Bx @ https://usebx.com. Having found no library capable of formatting the more unusual currencies
they decided to create their own and release it under an MIT Licence.
↪ Give Bx a try if you ever need a tool for invoicing, expenses or project management :)
This library is maintained by OSREC Technologies in London. Bugs and issues should be reported via github. If you use the library, we appreciate a mention or a link back to https://osrec.co.uk :)
Setup
https://github.com/osrec/currencyFormatter.js/archive/master.zip
Clone Github Repository:
git clone https://github.com/osrec/currencyFormatter.js.git
Install via npm:
Reference in your HTML as shown below - the library has no dependecies :)
<script type='text/javascript' src='currencyFormatter.js'></script>
<!--OR-->
<script type='text/javascript' src='currencyFormatter.min.js'></script>
Also available via cdnjs.com (https://cdnjs.com/libraries/currencyformatter.js)
Usage
› Basic Formatting
Formatting a number is pretty straightforward with the OSREC.CurrencyFormatter.format(number, parameters) method. Simply pass in your number along with the required parameters. The parameters can include the following:
var parameters =
{
currency: 'EUR', // If currency is not supplied, defaults to USD
symbol: '€', // Overrides the currency's default symbol
locale: 'fr', // Overrides the currency's default locale (see supported locales)
decimal: ',', // Overrides the locale's decimal character
group: '.', // Overrides the locale's group character (thousand separator)
pattern: '#,##0.00 !' // Overrides the locale's default display pattern
// The pattern follows standard unicode currency pattern notation.
// comma = group separator, dot = decimal separator, exclamation = currency symbol
}
Usually, you will not need to specify all the parameters, and can simply specify the currency (and the locale, if needed). The library is aware of the appropriate format to use for every currency and locale.
OSREC.CurrencyFormatter.format(2534234, { currency: 'INR' }); // Returns ₹ 25,34,234.00
OSREC.CurrencyFormatter.format(2534234, { currency: 'EUR' }); // Returns 2.534.234,00 €
OSREC.CurrencyFormatter.format(2534234, { currency: 'EUR', locale: 'fr' }); // Returns 2 534 234,00 €
› Format all element values as currency
If you need to convert all elements that contain numerical values into well formatted currencies, you can do this easily using the OSREC.CurrencyFormatter.formatAll(parameters) method. Simply pass in your element selector via the selector parameter, along with the currency (you can also override a whole bunch of additional parameters - see above for more details).
<div class='money'> 1234536.32 </div>
<div class='money'> 8798458.11 </div>
// Applies a single currency format to all selected elements
OSREC.CurrencyFormatter.formatAll(
{
selector: '.money',
currency: 'EUR'
});
› Format each element with a specific currency
The OSREC.CurrencyFormatter.formatEach(selector) method can be used to update a range of different currency values on a page by specifying the currency in the data-ccy attribute.
<div class='money' data-ccy='EUR'> 1234564.58 </div>
<div class='money' data-ccy='GBP'> 8798583.85 </div>
<div class='money' data-ccy='CHF'> 0.9754 </div>
<div>Your INR value is: <span class='money' data-ccy='INR'> 322453.9754 </span></div>
OSREC.CurrencyFormatter.formatEach('.money');
› Fully bespoke data formatter
The OSREC.CurrencyFormatter.getFormatter(parameters) method returns a bespoke formatting function that can be used to format currencies. This is the most efficient way to format a large number of currencies.
<input id='frenchEuroInput' value='78234564.5815899' />
// Once generated, the formatter below can used over
// and over again to format any number of currencies
var frenchEuroFormatter = OSREC.CurrencyFormatter.getFormatter
({
// If currency is not supplied, defaults to USD
currency: 'EUR',
// Use to override the currency's default symbol
symbol: '€',
// Use to override the currency's default locale - every locale has
// preconfigured decimal, group and pattern
locale: 'fr',
// Use to override the locale's default decimal character
decimal: ',',
// Use to override the locale's default group (thousand separator) character
group: '.',
// Use to override the locale's default display pattern
// Note comma = group separator, dot = decimal separator, exclamation = symbol
// Follows standard unicode currency pattern
pattern: '#,##0.00 !',
// Return this value if the input value is not a valid number
// Defaults to '0'
valueOnError: '0'
});
var val = document.getElementById('frenchEuroInput').value;
var formattedVal = frenchEuroFormatter(val);
document.getElementById('frenchEuroInput').value = formattedVal;
› Negative and Zero Formats
If you need to specify separate formats for negative numbers, positive numbers and zeros, you may do so by splitting them with a semi-colon like so: positivePattern;negativePattern;zeroPattern. The example below defines a bespoke pattern for the Swiss Franc (CHF), where the negative numbers are formatted with enclosing brackets and zeros are formatted to 2 decimal places.
<div class='money'> 7564.58 </div>
<div class='money'> -4583.85 </div>
<div class='money'> 0 </div>
OSREC.CurrencyFormatter.formatAll
({
selector: '.money',
currency: 'CHF',
pattern: '#,##0.00 !;(#,##0.00 !);0.00 !'
});
› Parsing
If you have currency values formatted as text in a particular locale, use the OSREC.CurrencyFormatter.parse() function to convert to a Number.
OSREC.CurrencyFormatter.parse('€ 100,99', { locale: 'it' }); // Returns 100.99
OSREC.CurrencyFormatter.parse('€ -99,50', { locale: 'it' }); // Returns -99.5
OSREC.CurrencyFormatter.parse('$ 11/25', { decimal: '/' }); // Returns 11.25
› Value on Error
If the input value is not a valid number, the formatter will return '0'. You may override this as follows:
OSREC.CurrencyFormatter.format('10', { currency: 'USD', valueOnError: 'Please enter a valid number!' });
OSREC.CurrencyFormatter.format('abcd', { currency: 'USD', valueOnError: 'Please enter a valid number!' });
› Post Format Function
Sometimes you may wish to post process your formatted numbers. For example, to make negative numbers appear red and positive numbers green. This can be easily done via the postFormatFunction option. This function will be called, passing in the numerical value, along with the formatted string as arguments. NOTE: the function will NOT be called if the input value is not a valid number.
var dollarFormatterWithColor = OSREC.CurrencyFormatter.getFormatter
({
currency: 'USD',
postFormatFunction: function(value, formattedValue)
{
var textColor;
if(value < 0) { textColor = '#CC0000'; }
else { textColor = '#00CC00'; }
return "<span style='color: " + textColor + "'>" + formattedValue + "</span>";
}
});
dollarFormatterWithColor(1234.56);
dollarFormatterWithColor(-9876.54);
Supported Currencies
The library currently supports the following currencies straight out of the box :)
Supported Locales
We use the standard ISO 2 digit language and country codes to define locales (as per the Unicode Common Locale Data Repository). The library supports the below locales (yes, all 715 of them!).
In case you're not sure what a locale is, it is simply a set of parameters that define the standard language and regional preferences for someone using a
particular language, in a particular region.