CurrencyFormatter.js

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

<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.