Javascript Number Formatter

2.0.9 · active · verified Sun Apr 19

number-format.js is a lightweight and performant JavaScript library designed for formatting numerical values using mask patterns. Currently at stable version 2.0.9, it focuses on providing a small footprint (under 2KB production size) and fast execution. It supports a wide array of masking symbols for forced and optional digits, positive/negative signs, and flexible thousands/decimal separators, accommodating various international numbering conventions. A key feature is its ability to automatically round numbers. Unlike more comprehensive internationalization libraries such as `Intl.NumberFormat`, `number-format.js` intentionally limits its scope, specifically not handling scientific/engineering notation, dates, or phone numbers. Its primary differentiator is its simplicity and speed for number mask formatting, making it suitable for scenarios where bundle size and performance are critical.

Common errors

```
TypeError: (0 , number_format_js_1.format) is not a function
```
cause Attempting to import the default `format` function as a named import in an ESM environment.

fix Change the import statement from `import { format } from 'number-format.js';` to `import format from 'number-format.js';`
```
Output '1234567,890' when expecting '1,234,567' with mask '#,###'
```
cause The library defaults a single non-digit symbol in the mask to be the decimal separator.

fix To force the symbol as a thousands separator, add a trailing non-mask symbol (e.g., a period) to define the decimal: `format('#,###.', 1234567.890)` to get `1,234,567`.
```
Prefix or suffix characters (e.g., 'USD ') are unexpectedly stripped or not appearing in the output.
```
cause The prefix/suffix contains characters (numbers, dashes, plus signs) that the formatter is explicitly designed to exclude when used as general prefix/suffix symbols, or it's incorrectly positioned in the mask.

fix Ensure that literal prefixes/suffixes outside the core numerical pattern do not contain `0-9`, `-`, or `+`. For complex cases, apply the prefix/suffix as string concatenation *after* the `format` call: `'$' + format('#,##0.00', 123.45)`.

Warnings

breaking Version 2.0.0 introduced the `enforceMaskSign` option, which significantly alters how positive and negative signs are handled within the mask. Code relying on previous sign display behavior, especially for negative numbers or explicit positive signs, may need adjustment.
Fix: Review mask patterns involving `+` or `-` symbols and explicitly use the `enforceMaskSign: true` option if signs should be enforced according to the mask rather than the value's inherent sign.
gotcha When a mask contains only a single non-digit symbol (e.g., `#,###`), the library will always interpret this symbol as the decimal separator by default, even if it logically should be a thousands separator. This can lead to unexpected output where numbers like `1234567.890` formatted with `#,###` become `1234567,890`.
Fix: To force a single symbol to be used as a thousands separator, append a trailing non-mask symbol (e.g., a period) to the end of the mask, such as `#,###.` This explicitly defines the last symbol as the decimal, forcing others to be separators.
gotcha While the library supports prefixes and suffixes within the mask (e.g., `'$ #,###.00'`), the README states that a prefix or suffix *cannot* include any numbers (`0-9`), dashes (`-`), or plus signs (`+`). This is somewhat ambiguous as mask examples show `$` working, which implies this limitation primarily applies to non-mask symbols 'outside' the numerical pattern.
Fix: Avoid using numerical digits, dashes, or plus signs as literal prefix/suffix characters within the mask itself if they are intended as non-formatting text. For complex prefixes/suffixes, consider concatenating them before/after the formatted string: `'$' + format('#,##0.00', 123.45)`.
gotcha This library is a dedicated number formatter with specific limitations. It does not support scientific/engineering notation, date formatting, or phone number formatting. Attempting to use it for these purposes will yield incorrect results.
Fix: For date formatting, use `Intl.DateTimeFormat` or a dedicated date library like `date-fns`. For phone numbers, use a specialized library like `libphonenumber`. For scientific notation, utilize JavaScript's built-in `Number.prototype.toExponential()` or `Intl.NumberFormat` with `notation: 'scientific'`.

Install

npm install number-format.js npm
yarn add number-format.js yarn
pnpm add number-format.js pnpm

Imports

format
wrong:
```
import { format } from 'number-format.js';
```
correct:
```
import format from 'number-format.js';
```
The library exports the `format` function as its default export for ESM.
format
wrong:
```
const { format } = require('number-format.js');
```
correct:
```
const format = require('number-format.js');
```
For CommonJS environments, the module directly exports the `format` function.

Quickstart

Demonstrates basic number formatting, currency handling, the `enforceMaskSign` option, and custom separators.

import format from 'number-format.js';

// Basic number formatting
console.log(`Formatted 1234567.890 with '#,##0.####': ${format("#,##0.####", 1234567.890)}`);
// Expected: "1,234,567.89"

// Currency formatting with prefix
console.log(`Formatted -1234567.890 with '$ #,###.00': ${format("$ #,###.00", -1234567.890)}`);
// Expected: "$ -1,234,567.89"

// Using enforceMaskSign option (added in v2.0.0)
console.log(`Formatted -1234567.890 with '$ #,###.00' and enforceMaskSign: ${format("$ #,###.00", -1234567.890, { enforceMaskSign: true })}`);
// Expected: "$ 1,234,567.89"

// Forcing positive sign
console.log(`Formatted 1234567.890 with '$ +#,###.00' and enforceMaskSign: ${format("$ +#,###.00", 1234567.890, { enforceMaskSign: true })}`);
// Expected: "$ +1,234,567.89"

// Custom decimal and thousands separators
console.log(`Formatted 98765.432 with '#.##0,00': ${format("#.##0,00", 98765.432)}`);
// Expected: "98.765,43"

view raw JSON →