number-format.js

Javascript Number Formatter

Lightweight & Fast JavaScript Number Formatter

Introduction

This standalone number formatter^† is intended to be short and fast. As they are the main factors for a high performance JavaScript app. Development release is as short as < 120 lines including license info, blank lines and comments. And production release is less than 1,200 bytes.

format( "#,##0.####", 1234567.890 );  // output: "1,234,567.89"
format( "$ #,###.00", -1234567.890 ); // output: "$ -1,234,567.89"

// Added in v2.0.0
format( "$ #,###.00", -1234567.890, {enforceMaskSign: true});  // output: "$ 1,234,567.89"
format( "$ -#,###.00", -1234567.890, {enforceMaskSign: true}); // output: "$ -1,234,567.89"
format( "$ +#,###.00", -1234567.890, {enforceMaskSign: true}); // output: "$ -1,234,567.89"
format( "$ +#,###.00", 1234567.890, {enforceMaskSign: true});  // output: "$ +1,234,567.89"

† Initial development release of this code was written by KPL and hosted at Google Code.

Features

• Short, fast, flexible yet standalone.
• Accept standard number formatting like #,##0.00 or with negation -000.####.
• Accept any country format like # ##0,00, #,###.##, #'###.## or any type of non-numbering symbol.
• Accept any numbers of digit grouping. #,##,#0.000 or #,###0.## are all valid.
• Accept any redundant/fool-proof formatting. ##,###,##.# or 0#,#00#.###0# are all OK.
• Auto number rounding.
• Simple interface, just supply mask & value like this: format( "0.0000", 3.141592).
• Include a prefix & suffix with the mask.

Limitations

• No scientific/engineering formatting.
• Not for date or phone formation.
• No color control.
• No prefix or suffix is allowed except leading negation symbol. So $#,##0.00 or #,###.##USD will not yield expected outcome. Use '$'+format('#,##0.00', 123.45) or format('#,##0.00', 456.789) + 'USD'
• The prefix or suffix can not include any numbers (0-9), dashes (-), or plus signs (+).

Installation

npm package

npm install --save number-format.js

Note

When only one symbol is supplied, the library will always treat that symbol as a decimal. For example, format( '#,###', 1234567.890) will output 1234567,890.

To force a single symbol to be used as a separator, add a trailing symbol. In this example, a period is added to the end of the mask - format( '#,###.', 1234567.890) - resulting in it being used as a decimal and forcing the first symbol to be the separator and return this output: 1,234,567.

Demos

A demo/sample page with few examples is provided (demo).

And a jsFiddle was created to aid in testing: https://jsfiddle.net/Mottie/t2etyodx/

Recent Changes

View the complete change log here.

v2.0.0 – 2.0.4 (2018-10-26)

• Add ignoreSign option (modified to enforeceMaskSign!).
• Switch to XO, AVA & rollup.
• Meta: Update dot files & remove bower support.
• Code cleanup & convert to ES2015.
  • Rename ignoreSign to enforceMaskSign (default false).
  • Reduce code complexity.
  • Export as node module.
  • Update TS with options.
  • Switch demo to use lib file & highlight valid results.
• Switch from Grunt to rollup.
• Switch from IIFE to UMD output.

v1.1.12 (2018-09-05)

• Core
  • Different Handling for Negative "-" and Positive "+" Signs. See pull #11; thanks @hyyan!
  • Prevent JS error when passing a string.
• Readme:
  • Update log.
• Meta:
  • Add typescript support. See pull #8; thanks @chuv!
• Demo:
  • Fix prettify loading.
  • Use https. Fixes issue #13.

v1.1.11 (2017-01-31)

• Readme:
  • Update log.
  • Add playground link.
  • Reword note.
• Meta:
  • Update dependencies.
  • Remove GPL portion of the license & update package.json entry.
  • Fix bower.json "main" reference.
• Build:
  • Fix build process to use the updated package.json license format.