numfmt – a spreadsheet number formatter

The numfmt library formats numbers according to a specifier string as defined in [ECMA-376][ecma]. The library tries its best to emulate the inns and outs of what the Excel spreadsheet software does.

The library is written in pure JavaScript and has no dependencies. It is comparable to the [SSF][ssf] with some minor interface exceptions.

Features

Why use this rather than the battle tested SSF? You may have no need to but numfmt is fully open source, has equivalent (if not better) formatting capabilities, built in international support, customizability, input parsing, and may run about twice as fast in most cases.

Adding locales is simple but those included are:

• Arabic (ar)
• Armenian (hy)
• Azeri (az)
• Belarusian (be)
• Bengali (bn)
• Bulgarian (bg)
• Burmese (my)
• Catalan (ca)
• Chinese (zh_CN, zh_HK, zh_TW)
• Croatian (hr)
• Czech (cs)
• Danish (da)
• Dutch (nl)
• English (en, en_AU, en_CA, en_GB, en_IE)
• Filipino (fil)
• Finnish (fi)
• French (fr, fr_CA, fr_CH)
• Georgian (ka)
• German (de, de_CH)
• Greek (el)
• Gujarati (gu)
• Hebrew (he)
• Hindi (hi)
• Hungarian (hu)
• Icelandic (is)
• Indonesian (id)
• Italian (it, it_CH)
• Japanese (ja)
• Kannada (kn)
• Kazakh (kk)
• Korean (ko)
• Latvian (lv)
• Lithuanian (lt)
• Malayalam (ml)
• Marathi (mr)
• Mongolian (mn)
• Norwegian (nb, no)
• Polish (pl)
• Portuguese (pt, pt_BR)
• Punjabi (pa)
• Romanian (ro)
• Russian (ru)
• Serbian (sr)
• Slovak (sk)
• Slovenian (sl)
• Spanish (es, es_AR, es_BO, es_CL, es_CO, es_EC, es_MX, es_PY, es_UY, es_VE)
• Swedish (sv)
• Tamil (ta)
• Telugu (te)
• Thai (th)
• Turkish (tr)
• Ukrainian (uk)
• Vietnamese (vi)
• Welsh (cy)

The library is made to work with current generation spreadsheets and so it does not support the 1904 date system. It does not have built in tables for formats addressable by offsets, you are expected to maintain those yourself.

Installing

If you don't want to download and build numfmt yourself, the library is conveniently provided as an NPM package:

$ npm install numfmt

Using

import { format } from "numfmt";

const output = format("#,##0.00", 1234.56);
console.log(output);

The full API documentation is available under API.md.

Format syntax

Microsoft have excellent documentation on how the format works. Here are some quick basics:

A format pattern is divided into 4 sections: <POSITIVE>;<NEGATIVE>;<ZERO>;<TEXT>

Only the first section is mandatory, the others are filled in as needed. The sections consist of symbols to indicate what to emit. The symbols are case insensitive:

| Symbol | Result | Description |-- |-- |-- | 0 | Digit or Zero | 7 formatted with 00 will emit "07" | # | Digit if needed | 7 formatted with ## will emit "7" | ? | Digit or Space | 7 formatted with ?? will emit " 7" | . | Decimal point | | , | Thousands separator | 1234 formatted with #,##0 will emit "1,234". The emitted grouping character depends on the locale used. | % | Percentage | Number is multiplied by 100 before it is shown. .7 formatted with 0% will emit "70%" | E-, E+ | Exponential format | 12200000 formatted with 0.00E+00 will emit "1.22E+07" | $, -, +, /, (, ), | Pass-through | The symbol is printed as-is. | \ | Escape | Pass the the next character through as-is. | * | Fill | Repeat the next character in the format enough times to fill the column to its current width. By default numfmt emits nothing when this is used. | _ | Skip width | Skip the width of the next character. By default numfmt emits only a single space when this is used. | "text" | Pass-through | Pass through whatever text is inside the quotation marks as-is. 7 formatted with 0 "bells" will emit "7 bells" | @ | Text value | When value is a text, emit it as is: foo formatted with "bar"@"bar" will emit "barfoobar" | yy | Years | Two digit year | yyyy | Years | Four digit year | m | Month | 1–12 | mm | Month | 01–12 | mmm | Short month | Month name abbreviation (Jan–Dec). Names are locale dependent. | mmmm | Month name | Full month name (January–December). Names are locale dependent. | mmmmm | Month name | Single letter month abbreviation (J–D). Names are locale dependent. | d | Days | 1–31 | dd | Days | 01–31 | ddd | Weekdays | Sun–Sat | dddd | Weekdays | Sunday–Saturday | h | Hours | 0–23 or 1–12 | hh | Hours | 00–23 or 01–12 | m | Minutes | 0–59 | mm | Minutes | 00–59 | s | Seconds | 0–59 | ss | Seconds | 00–59 | AM/PM | 12h clock | Sets clock to 12h and emits AM or PM. | A/P | 12h clock | Sets clock to 12h and emits A or P. | [h] | Hours | Elapsed time in hours | [m] | Minutes | Elapsed time in minutes | [s] | Seconds | Elapsed time in seconds

The <POSITIVE> and <NEGATIVE> sections may optionally have conditionals. A condition is set by a comparison operator followed by a number, followed by the regular format symbols, surrounded by square brackets: [>=-2.5]#,##0.0. The supported set of operators is: = > < >= <= <>

• There must not be more than 4 sections.
• There must not be more than 2 conditional sections.
• There must not be numerical or date emitting symbol in the (4th) text part.