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 38,039 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
ECMAScript 2025 introduces Iterator Helpers, Set methods, JSON modules, and more in its latest spec update approved by Ecma in June 2025.
Security News
A new Node.js homepage button linking to paid support for EOL versions has sparked a heated discussion among contributors and the wider community.
Research
North Korean threat actors linked to the Contagious Interview campaign return with 35 new malicious npm packages using a stealthy multi-stage malware loader.