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.
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:
ar)hy)az)be)bn)bg)my)ca)zh_CN, zh_HK, zh_TW)hr)cs)da)nl)en, en_AU, en_CA, en_GB, en_IE)fil)fi)fr, fr_CA, fr_CH)ka)de, de_CH)el)gu)he)hi)hu)is)id)it, it_CH)ja)kn)kk)ko)lv)lt)ml)mr)mn)nb, no)pl)pt, pt_BR)pa)ro)ru)sr)sk)sl)es, es_AR, es_BO, es_CL, es_CO, es_EC, es_MX, es_PY, es_UY, es_VE)sv)ta)te)th)tr)uk)vi)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.
If you don't want to download and build numfmt yourself, the library is conveniently provided as an NPM package:
$ npm install numfmt
import { format } from "numfmt";
const output = format("#,##0.00", 1234.56);
console.log(output);
The full API documentation is available under API.md.
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: = > < >= <= <>
FAQs
Full Excel style number formatting
The npm package numfmt receives a total of 6,985 weekly downloads. As such, numfmt popularity was classified as popular.
We found that numfmt demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Research
A malicious npm package disguised as a WhatsApp client is exploiting authentication flows with a remote kill switch to exfiltrate data and destroy files.
Security News
PyPI now supports digital attestations, enhancing security and trust by allowing package maintainers to verify the authenticity of Python packages.
Security News
GitHub removed 27 malicious pull requests attempting to inject harmful code across multiple open source repositories, in another round of low-effort attacks.