CurrencyFormatter.js

About

CurrencyFormatter.js allows users to format numbers in a variety of currency formats. It contains 155 currency definitions, and 715 locale definitions right out of the box, and can handle unusually formatted currencies, such as the INR and is completely configurable.

This library is lovingly maintained in London by OSREC Financial. It is available for both commercial and non-commercial use under the MIT licence. Bugs and issues should be reported via github. If you use the library, please do mention us :)

Setup

<script type='text/javascript' src='currencyFormatter.js'></script>	
<!--OR-->
<script type='text/javascript' src='currencyFormatter.min.js'></script>	

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 €

› Example 1: 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'
});

› Example 2: 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');

› Example 3: 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 !' 

});

var val = document.getElementById('frenchEuroInput').value;

var formattedVal = frenchEuroFormatter(val);

document.getElementById('frenchEuroInput').value = formattedVal;	

› Example 4: 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 !'
});

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.