accounting.js
accounting.js is a tiny JavaScript library by Open Exchange Rates, providing simple and advanced number, money and currency formatting.
<p>Features custom output formats, parsing/unformatting of numbers, easy localisation and spreadsheet-style column formatting (to line up symbols and decimals).</p>
<p>It's lightweight, has no dependencies and is suitable for all client-side and server-side JavaScript applications.</p>
<p><a href="http://twitter.com/share" class="twitter-share-button" data-count="horizontal" data-via="josscrowcroft" data-url="http://openexchangerates.github.io/accounting.js" data-text="accounting.js - JavaScript library for money/currency formatting">Tweet</a> <g:plusone size="medium"></g:plusone></p>
<ul>
<li><a href="#methods" title="library methods overvew">methods & examples</a>
<li><a href="#demo" title="demo">demo</a>
<li><a href="#instructions" title="instructions">instructions</a>
<li><a href="#documentation" title="documentation">documentation</a>
<li><a href="#roadmap" title="roadmap">roadmap</a>
<li><a href="#support" title="support">feedback / support</a>
<li><a href="#download" title="download">download</a>
<li><a href="#links" title="links">links</a>
</ul>
</section>
<section id="methods">
<h2>Library Methods</h2>
<h4><strong>formatMoney()</strong> - format any number into currency</h4>
<p>The most basic library function for formatting numbers as money values, with customisable currency symbol, precision (decimal places), and thousand/decimal separators:</p>
<pre class="prettyprint lang-js">// Default usage:
accounting.formatMoney(12345678); // $12,345,678.00
// European formatting (custom symbol and separators), can also use options object as second parameter: accounting.formatMoney(4999.99, "€", 2, ".", ","); // €4.999,99
// Negative values can be formatted nicely: accounting.formatMoney(-500000, "£ ", 0); // £ -500,000
// Simple format
string allows control of symbol position (%v = value, %s = symbol):
accounting.formatMoney(5318008, { symbol: "GBP", format: "%v %s" }); // 5,318,008.00 GBP
<h4><strong>formatColumn()</strong> - format a list of values for column-display</h4>
<p>This table demonstrates how <strong>accounting.js</strong> can take a list of numbers and money-format them with padding to line up currency symbols and decimal places</p>
<p>In order for the padded spaces to render correctly, the containing element must be CSS styled with <code>white-space: pre</code> (pre-formatted) - otherwise the browser will squash them into single spaces.</p>
<table id="demo-table">
<thead>
<tr>
<th>Original Number:</th>
<th>With accounting.js:</th>
<th>Different settings:</th>
<th>European format:</th>
<th>Symbol after value:</th>
</tr>
</thead>
<tbody></tbody>
</table>
<pre class="prettyprint lang-js">// Format list of numbers for display:
accounting.formatColumn([123.5, 3456.49, 777888.99, 12345678, -5432], "$ ");
<h4><strong>formatNumber()</strong> - format a number with custom precision and localisation</h4>
<p>The base function of the library, which takes any number or array of numbers, runs <code>accounting.unformat()</code> to remove any formatting, and returns the number(s) formatted with separated thousands and custom precision:</p>
<pre class="prettyprint lang-js">accounting.formatNumber(5318008); // 5,318,008
accounting.formatNumber(9876543.21, 3, " "); // 9 876 543.210
<h4><strong>toFixed()</strong> - better rounding for floating point numbers</h4>
<p>Implementation of toFixed() that treats floats more like decimal values than binary, fixing inconsistent precision rounding in JavaScript (where some .05 values round up, while others round down):</p>
<pre class="prettyprint lang-js">(0.615).toFixed(2); // "0.61"
accounting.toFixed(0.615, 2); // "0.62"
<h4><strong>unformat()</strong> - parse a value from any formatted number/currency string</h4>
<p>Takes any number and removes all currency formatting. Aliased as <code>accounting.parse()</code></p>
<pre class="prettyprint lang-js">accounting.unformat("£ 12,345,678.90 GBP"); // 12345678.9</pre>
</section>
<section id="demo">
<h2>Demo / Try it out</h2>
<h4>Money formatting:</h4>
<div class="well">
<p>Enter any number into the box and choose currency. Uses <code>accounting.formatMoney()</code>:</p>
<p>
<select id="demo-number-symbol">
<option value="$ ">$</option>
<option value="£ ">£</option>
<option value="HK$ ">HK$</option>
<option data-locale="european" value="€ ">€ </option>
</select>
<input type="text" maxlength="20" class="" id="demo-number-value" value="" />
</p>
<p>Result: <strong><span id="demo-number-result">$ 0.00</span></strong></p>
</div>
<h4>Column formatting:</h4>
<div class="well">
<p>Edit the values in the table to see how <strong>formatColumn()</strong> keeps them aligned:</p>
<table id="demo-column">
<tbody>
<tr>
<td><input type="text" value="1000000" maxlength="20" /></td>
<td class="output">$ 1,000,000.00</td>
<td class="output2">GBP 1,000,000</td>
</tr>
<tr>
<td><input type="text" value="-5000" maxlength="20" /></td>
<td class="output">$ -5,000.00</td>
<td class="output2">GBP (5,000)</td>
</tr>
<tr>
<td><input type="text" value="0" maxlength="20" /></td>
<td class="output">$ 0.00</td>
<td class="output2">GBP --</td>
</tr>
</tbody>
</table>
</div>
</section>
<section id="instructions">
<h2>Basic Instructions:</h2>
<p>1. Download the script and put it somewhere, then reference it in your HTML like so:</p>
<pre class="prettyprint"><script src="path/to/accounting.js"></script>
<script type="text/javascript"> // Library ready to use: accounting.formatMoney(5318008); </script>
<p>2. See the documentation and source-code for full method/parameter information.</p>
</section>
<section id="documentation">
<h2>Documentation</h2>
<p>Information on the parameters of each method. See <a href="#methods" title="accounting.js library methods">library methods</a> above for more examples. Optional parameters are in <code><em>[italics]</em></code>, with the default value indicated.</p>
<h4><strong>accounting.settings</strong></h4>
<pre class="prettyprint lang-js">// Settings object that controls default parameters for library methods:
accounting.settings = { currency: { symbol : "$", // default currency symbol is '$' format: "%s%v", // controls output: %s = symbol, %v = value/number (can be object: see below) decimal : ".", // decimal point separator thousand: ",", // thousands separator precision : 2 // decimal places }, number: { precision : 0, // default precision on numbers is 0 thousand: ",", decimal : "." } }
// These can be changed externally to edit the library's defaults: accounting.settings.currency.format = "%s %v";
// Format can be an object, with pos
, neg
and zero
:
accounting.settings.currency.format = {
pos : "%s %v", // for positive values, eg. "$ 1.00" (required)
neg : "%s (%v)", // for negative values, eg. "$ (1.00)" [optional]
zero: "%s -- " // for zero values, eg. "$ --" [optional]
};
// Example using underscore.js - extend default settings (also works with $.extend in jQuery): accounting.settings.number = _.defaults({ precision: 2, thousand: " " }, accounting.settings.number);
<h4><strong>accounting.formatMoney()</strong></h4>
<pre class="prettyprint lang-js">// Standard usage and parameters (returns string):
accounting.formatMoney(number,[symbol = "$"],[precision = 2],[thousand = ","],[decimal = "."],[format = "%s%v"])
// Second parameter can be an object: accounting.formatMoney(number, [options])
// Available fields in options object, matching settings.currency
:
var options = {
symbol : "$",
decimal : ".",
thousand: ",",
precision : 2,
format: "%s%v"
};
// Example usage: accounting.formatMoney(12345678); // $12,345,678.00 accounting.formatMoney(4999.99, "€", 2, ".", ","); // €4.999,99 accounting.formatMoney(-500000, "£ ", 0); // £ -500,000
// Example usage with options object: accounting.formatMoney(5318008, { symbol: "GBP", precision: 0, thousand: "·", format: { pos : "%s %v", neg : "%s (%v)", zero: "%s --" } });
// Will recursively format an array of values: accounting.formatMoney([123, 456, [78, 9]], "$", 0); // ["$123", "$456", ["$78", "$9"]]
<h4><strong>accounting.formatColumn()</strong></h4>
<pre class="prettyprint lang-js">// Standard usage and parameters (returns array):
accounting.formatColumn(list, [symbol = "$"],[precision = 2],[thousand = ","],[decimal = "."],[format = "%s%v"])
// Second parameter can be an object (see formatNumber for available options): accounting.formatColumn(list, [options])
// Example usage (NB. use a space after the symbol to add arbitrary padding to all values): var list = [123, 12345]; accounting.formatColumn(list, "$ ", 0); // ["$ 123", "$ 12,345"]
// List of numbers can be a multi-dimensional array (formatColumn is applied recursively): var list = [[1, 100], [900, 9]]; accounting.formatColumn(list); // [["$ 1.00", "$100.00"], ["$900.00", "$ 9.00"]]
<h4><strong>accounting.formatNumber()</strong></h4>
<pre class="prettyprint lang-js">// Standard usage and parameters (returns string):
accounting.formatNumber(number, [precision = 0], [thousand = ","], [decimal = "."])
// Second parameter can also be an object matching settings.number
:
accounting.formatNumber(number, [object])
// Example usage: accounting.formatNumber(9876543); // 9,876,543 accounting.formatNumber(4999.99, 2, ".", ","); // 4.999,99
// Example usage with options object: accounting.formatNumber(5318008, { precision : 3, thousand : " " });
// Will recursively format an array of values: accounting.formatNumber([123456, [7890, 123]]); // ["123,456", ["7,890", "123"]]
<h4><strong>accounting.toFixed()</strong></h4>
<pre class="prettyprint lang-js">// Standard usage and parameters (returns string):
accounting.toFixed(number, [precision = 0]);
// Example usage: accounting.toFixed(0.615, 2); // "0.62"
// Compare to regular JavaScript Number.toFixed()
method:
(0.615).toFixed(2); // "0.61"
<h4><strong>accounting.unformat()</strong></h4>
<pre class="prettyprint lang-js">// Standard usage and parameters (returns number):
accounting.unformat(string, [decimal]);
// Example usage: accounting.unformat("GBP £ 12,345,678.90"); // 12345678.9
// If a non-standard decimal separator was used (eg. a comma) unformat() will need it in order to work out // which part of the number is a decimal/float: accounting.unformat("€ 1.000.000,00", ","); // 1000000
</section>
<section id="roadmap">
<h2>Roadmap</h2>
<h4>Next Version:</h4>
<ul>
<li><s>Add more fine-grained control of formatting, with negatives and zero-values</s></li>
<li><s>Implement <code>map()</code> and type-checking helper methods to clean up API methods</s></li>
<li>Find performance bottlenecks and work on speed optimisations</li>
<li>Write more tests, docs and examples, add FAQ</li>
<li>Implement <a href="https://github.com/openexchangerates/accounting.js/issues/" title="accounting.js issues">feedback</a></li>
</ul>
<h4>Later:</h4>
<ul>
<li>Add padding parameter to override amount of space between currency symbol and value.</li>
<li>Add digit-grouping control, to allow eg. "$10,0000"</li>
<li>Add choice of rounding method for precision (up, down or nearest-neighbour).</li>
<li>Add several other general and excel-style money formatting methods.</li>
<li>Create NPM package, if there's demand for it.</li>
<li>Create wrapper for jQuery as a separate plugin (not in core) to allow eg. <code>$('td.accounting').formatMoney()</code></li>
</ul>
<p>See the <a href="https://github.com/openexchangerates/accounting.js/issues" title="accounting.js issues">Github Issues page</a> for currently active issues.</p>
</section>
<section id="support">
<h2>Feedback / Support</h2>
<p>Please create issues on the <a href="https://github.com/openexchangerates/accounting.js" title="accounting.js Github repository">accounting.js Github repository</a> if you have feedback or need support, or <a href="mailto:info@openexchangerates.org" title="Contact Open Exchange Rates">contact Open Exchange Rates here</a>.</p>
</section>
<section id="download">
<h2>Download</h2>
<ul>
<li><strong><a href="https://raw.github.com/openexchangerates/accounting.js/master/accounting.js" title="accounting.js">accounting.js</a></strong> - Latest version from Github (12kb)</li>
<li><strong><a href="https://raw.github.com/openexchangerates/accounting.js/master/accounting.min.js" title="accounting.min.js">accounting.min.js</a></strong> - Latest version from Github (3kb, minified)</li>
<li>Or check out the <a href="https://github.com/openexchangerates/accounting.js" title="accounting.js Github repository">accounting.js Github repository</a> for the full package.</li>
</ul>
</section>
<section id="links">
<h2>Links</h2>
<p>accounting.js is maintained by <strong><a href="https://openexchangerates.org" title="Open Exchange Rates free currency data API" target="_blank">Open Exchange Rates</a></strong> - the lightweight currency data API for startups, SMEs and Fortune 500s.</p>
<p>Feedback, support or questions? <strong><a href="mailto:info@openexchangerates.org" title="Contact Open Exchange Rates">Contact Open Exchange Rates</a></strong> for guidance.</p>
<p>Bugs, issues, suggestions or contributions? Please <strong><a href="https://github.com/openexchangerates/accounting.js" title="accounting.js Github repository">post them here</a></strong>.</p>
<p>accounting.js works great with <strong><a href="http://openexchangerates.github.com/money.js" title="money.js - JavaScript currency conversion library">money.js</a></strong> - the tiny (1kb) standalone JavaScript currency conversion library, for web & nodeJS</p>
<br />
<hr />
<p><a href="http://twitter.com/share" class="twitter-share-button" data-count="horizontal" data-via="josscrowcroft" data-url="http://openexchangerates.github.io/accounting.js" data-text="accounting.js - JavaScript library for money/currency formatting">Tweet</a> <g:plusone size="medium"></g:plusone></p>
</section>