The numfmt library formats numbers according to a specifier string as defined in ECMA-376. 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 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:
zh-CN or zh)zh-TW)cs)da)nl)en)fi)fr)de)el)hu)is)id)it)ja)ko)nb)pl)pt)ru)sk)es)sv)th)tr)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 numfmt from "numfmt";
// reusable function
const formatter = numfmt("#,##0.00");
const output = formatter(1234.56);
console.log(output);
// ... or just
const output = numfmt.format("#,##0.00", 1234.56);
console.log(output);
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. Like Excel's TEXT function, numFmt emits nothing when this is used. |
_ | Skip width | Skip the width of the next character. Like Excel's TEXT function, 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 |
Constructs a new formatter function with the specified options.
Pattern must be a string according to the ECMA-376 number format. Options should be an object of options. You may change defaults once for all instances using numfmt.options.
Returns a formatted string for the argument value. If options object is provided then it overrides the constructor options of those options provided.
Returns a true or false depending on if the pattern is a date pattern. The pattern is considered a date pattern if any of its sections contain a date symbol (see table above). Each section is restricted to to be either a number or date format.
Returns a true or false depending on if the pattern is a percentage pattern. The pattern is considered a percentage pattern if any of its sections contain a percentage symbol (see table above).
Returns a true or false depending on if the pattern is a text percentage pattern if its definition is composed of a single section that includes that text symbol (see table above). For example @ or @" USD" are text patterns but #;@ is not.
If the pattern defines colors this function will emit the color appropriate to the value. If no colors were specified this function returns "black".
import numfmt from "numfmt";
const formatter = numfmt("[green]#,##0;[red]-#,##0");
const color = formatter.color(-10);
console.log(color); // "red"
Stores information and internals of the parsed format string.
import numfmt from "numfmt";
console.log(numfmt("#,##0.00").info);
// will emit...
{
type: 'number',
isDate: false,
isText: false,
isPercent: false,
maxDecimals: 0,
color: 0,
parentheses: 0,
grouped: 1,
code: ',2',
scale: 1,
level: 4,
};
| Member | Note |
|---|---|
type | A string identifier for the type of the number formatter. The possible values are: currency , date, datetime, error, fraction, general, grouped, number, percent, scientific, text, time |
isDate , isText, isPercent | Correspond to the output from same named functions found on the formatters. |
maxDecimals | The maximum number of decimals this format will emit. |
color | 1 if the format uses color on the negative portion of the string, else a 0. This replicates Excel's CELL("color") functionality. |
parentheses | 1 if the positive portion of the number format contains an open parenthesis, else a 0. This is replicates Excel's CELL("parentheses") functionality. |
grouped | 1 if the positive portion of the format uses a thousands separator, else a 0. |
code | Corresponds to Excel's CELL("format") functionality. It is should match Excel's quirky behaviour fairly well. See, Microsoft's documentation. |
level | An arbirarty number that represents the format's specificity if you want to compare one to another. Integer comparisons roughly match Excel's resolutions when it determines which format wins out. |
scale | The multiplier used when formatting the number (100 for percentages). |
Stores information about date code use in the format string.
import numfmt from "numfmt";
console.log(numfmt("dd/mm/yyyy").dateInfo);
// will emit...
{
year: true,
month: true,
day: true,
hours: false,
minutes: false,
seconds: false,
clockType: 24
};
| Member | Note |
|---|---|
| year | If any y or b operator was found in the pattern. |
| month | If any m operator was found in the pattern. |
| day | If any d operator was found in the pattern (including ones that emit weekday). |
| hours | If any h operator was found in the pattern. |
| minutes | If any :m operator was found in the pattern. |
| seconds | If any s operator was found in the pattern. |
| clockType | Will be set to 12 if AM/PM operators are being used in the formatting string, else it will be set to 24. |
Parses the format pattern and formats the value according to the pattern, and optionally, any options. See definition above.
Return a value rounded to the specified amount of places. This is the rounding function used by the formatter (symmetric arithmetic rounding).
Parse a BCP 47 locale tag and emit an object of its parts. Intended for internal use.
Used by the formatter to pull a locate from its registered locales. If subtag isn't available but the base language is, the base language is used. So if en-CA is not found, the formatter tries to find en else it returns a null.
Register locale data for a language. The full data object looks like this:
{
group: "\u00a0", // non-breaking space
decimal: ".",
positive: "+",
negative: "-",
percent: "%",
exponent: "E",
nan: "NaN",
infinity: "∞",
ampm: [ "AM", "PM" ],
// gregorian calendar
mmmm: [ "January", "February", … ],
mmm: [ "Jan", "Feb", … ],
dddd: [ "Sunday", "Monday", … ],
ddd: [ "Sun", "Mon", … ],
// islamic calendar
mmmm6: [ "Muharram", "Safar", … ],
mmm6: [ "Muh.", "Saf.", … ],
}
The data object does not need to be complete, it will fall back to defaults (mostly English) for any missing properties. Adding support for Faroese you would require only passing the data different from the defaults:
numfmt.addLocale({
group: ".",
decimal: ",",
mmmm: [ "januar", "februar", … ],
mmm: [ "jan", "feb", … ],
dddd: [ "sunnudagur", "mánadagur", … ],
ddd: [ "sun", "mán", … ],
}, "fo-FO");
If the language tag provided has a subtag and a base language does not exit, the locale is register to both. In the Faroese example above both fo and fo-FO will be created.
Returns a true or false depending on if the pattern is a date pattern. The pattern is considered a date pattern if any of its sections contain a date symbol (see table above). Each section is restricted to to be either a number or date format.
For compatibility reasons, this function is also available as numfmt.is_date(format).
Returns a true or false depending on if the pattern is a percentage pattern. The pattern is considered a percentage pattern if any of its sections contain a percentage symbol (see table above).
Returns a true or false depending on if the pattern is a text percentage pattern if its definition is composed of a single section that includes that text symbol (see table above). For example @ or @" USD" are text patterns but #;@ is not.
Returns an object detailing the properties and internals of the format. See formatter.info for details.
Attempt to parse a "spreadsheet input" string input and return its value and format. If the input was not recognized or valid, the function returns a null, for valid input it returns an object with two properties:
v: The parsed value. For dates, this will be an Excel style serial date unless the nativeDate option is used.z: (Optionally) the number format string of the input. This property will not be present if it amounts to the General format.numfmt.parseValue() recognizes a wide range of dates and date-times, times, numbers, and booleans. Some examples:
// basic number
numfmt.parseValue("-123"); // { v: -123 }
// formatted number
numfmt.parseValue("$1,234"); // { v: 1234, z: "$#,##0" }
// a percent
numfmt.parseValue("12.3%"); // { v: 0.123, z: "0.00%" }
// a date
numfmt.parseValue("07 October 1984"); // { v: 30962, z: 'dd mmmm yyyy' }
// an ISO formatted date-time
numfmt.parseValue("1984-09-10 11:12:13.1234"); // { v: 30935.46681855787, z: "yyyy-mm-dd hh:mm:ss" }
// a boolean
numfmt.parseValue("false"); // { v: false }
The formatting string outputted may not correspond exactly to the input. Rather, is it composed of certain elements which the input controls. This is comparable to how Microsoft Excel and Google Sheets parse pasted input. Some things you may expect:
.00 regardless of how many digits were shown in the input.(1,234)] will not include the parentheses in the format string (the value will still by negative.)0.00E+00.Internally the parser calls, numfmt.parseNumber, numfmt.parseDate, numfmt.parseTime and numfmt.parseBool. They work in the same way exept with a more limited scope. If you do not want to be this liberal then use those functions.
Be warned that the parser do not (yet) take locale into account so all input is assumed to be in "en-US". This means that 1,234.5 will parse, but 1.234,5 will not. Similarily, the order of date parts will be US centeric. This may change in the future so be careful what options you pass the functions.
The parser does not listen to globally set default options (as set with numfmt.options).
Parse a numeric string input and return its value and format. If the input was not recognized or valid, the function returns a null, for valid input it returns an object with two properties:
v: the parsed value.z: the number format of the input (if applicable).See numfmt.parseValue for more details.
Parse a date or datetime string input and return its value and format. If the input was not recognized or valid, the function returns a null, for valid input it returns an object with two properties:
v: the parsed value (in Excel serial time).z: the number format of the input.See numfmt.parseValue for more details.
Parse a time string input and return its value and format. If the input was not recognized or valid, the function returns a null, for valid input it returns an object with two properties:
v: the parsed value (in Excel serial time).z: the number format of the input.See numfmt.parseValue for more details.
Parse a string input and return its boolean value. If the input was not recognized or valid, the function returns a null, for valid input it returns an object with one property:
v: the parsed value.See numfmt.parseValue for more details.
Convert a native JavaScript Date, or array to an spreadsheet serial date. Can be set to ignore timezone information with { ignoreTimezone: true } if you are passing in Date objects.
Returns a serial date number if input was a Date object or an array, otherwise it will pass the input through untouched.
// input as Date
numfmt.dateToSerial(new Date(1978, 5, 17)); // 28627
// input as [ Y, M, D, h, m, s ]
numfmt.dateToSerial([ 1978, 5, 17 ]); // 28627
// other input
numfmt.dateToSerial("something else"); // "something else"
This function does not listen to globally set default options (as set with numfmt.options).
Convert a spreadsheet style serial date value to an Array of date parts ([ Y, M, D, h, m, s ]) or, if the nativeDate option is used, a native JavaScript Date.
// output as [ Y, M, D, h, m, s ]
numfmt.dateToSerial(28627); // [ 1978, 5, 17, 0, 0 ,0 ]
// output as Date
numfmt.dateFromSerial(28627, { nativeDate: true }); // new Date(1978, 5, 17)
This function does not listen to globally set default options (as set with numfmt.options).
Set a default option or options for the formatter. This will affect all formatters unless they have overwritten options at construction time. Calling numfmt.options(null) will reset to internal defaults.
// basic "default" formatter
const weekdayEN = numfmt("dddd");
weekdayEN(1234); // "Monday"
// setting a new default
numfmt.options({ locale: "is" });
// call the same formatter
weekdayEN(1234); // "mánudagur"
// construct a new formatter with a locale
const weekdayFR = numfmt("dddd", { locale: "fr", });
weekdayFR(1234); // "lundi"
// override settings at call-time
weekdayEN(1234, { locale: "pl" }); // "poniedziałek"
weekdayFR(1234, { locale: "pl" }); // "poniedziałek"
As well as allowing locale customization, numfmt behaviour can be controlled with other options:
| Member | Type | Default | Note |
|---|---|---|---|
| locale | string | "" | A BCP 47 string tag. Locale default is english with a \u00a0 grouping symbol (see numfmt.addLocale). |
| throws | boolean | true | Should the formatter throw an error if a provided pattern is invalid. If not, a formatter will be constructed which only ever outputs an error string (see invalid in this table). |
| invalid | string | "######" | The string emitted when no-throw mode fails to parse a pattern. |
| nbsp | boolean | true | By default the formatters will emit non-breaking-space rather than a regular space when emitting the formatted number. Setting this to false will make it use regular spaces instead. |
| leap1900 | boolean | true | Simulate the Lotus 1-2-3 1900 leap year bug. It is a requirement in the Ecma OOXML specification so it is on by default. |
| dateErrorThrows | boolean | false | Should the formatter throw an error when trying to format a date that is out of bounds? |
| dateErrorNumber | boolean | true | Should the formatter switch to a General number format when trying to format a date that is out of bounds? |
| overflow | string | "######" | The string emitted when a formatter fails to format a date that is out of bounds. |
| dateSpanLarge | boolean | true | Extends the allowed range of dates from Excel bounds (1900–9999) to Google Sheet bounds (0–99999). |
| ignoreTimezone | boolean | false | Normally when date objects are used with the formatter, time zone is taken into account. This makes the formatter ignore the timezone offset. |
| nativeDate | boolean | false | when using the numfmt.parseDate, numfmt.parseValue and numfmt.dateFromSerial functions, the output will be a Date object. |
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.