{"id":11469,"library":"number-format.js","title":"Javascript Number Formatter","description":"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.","status":"active","version":"2.0.9","language":"javascript","source_language":"en","source_url":"git://github.com/Mottie/javascript-number-formatter","tags":["javascript","number","format","formatter","currency","typescript"],"install":[{"cmd":"npm install number-format.js","lang":"bash","label":"npm"},{"cmd":"yarn add number-format.js","lang":"bash","label":"yarn"},{"cmd":"pnpm add number-format.js","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"The library exports the `format` function as its default export for ESM.","wrong":"import { format } from 'number-format.js';","symbol":"format","correct":"import format from 'number-format.js';"},{"note":"For CommonJS environments, the module directly exports the `format` function.","wrong":"const { format } = require('number-format.js');","symbol":"format","correct":"const format = require('number-format.js');"}],"quickstart":{"code":"import format from 'number-format.js';\n\n// Basic number formatting\nconsole.log(`Formatted 1234567.890 with '#,##0.####': ${format(\"#,##0.####\", 1234567.890)}`);\n// Expected: \"1,234,567.89\"\n\n// Currency formatting with prefix\nconsole.log(`Formatted -1234567.890 with '$ #,###.00': ${format(\"$ #,###.00\", -1234567.890)}`);\n// Expected: \"$ -1,234,567.89\"\n\n// Using enforceMaskSign option (added in v2.0.0)\nconsole.log(`Formatted -1234567.890 with '$ #,###.00' and enforceMaskSign: ${format(\"$ #,###.00\", -1234567.890, { enforceMaskSign: true })}`);\n// Expected: \"$ 1,234,567.89\"\n\n// Forcing positive sign\nconsole.log(`Formatted 1234567.890 with '$ +#,###.00' and enforceMaskSign: ${format(\"$ +#,###.00\", 1234567.890, { enforceMaskSign: true })}`);\n// Expected: \"$ +1,234,567.89\"\n\n// Custom decimal and thousands separators\nconsole.log(`Formatted 98765.432 with '#.##0,00': ${format(\"#.##0,00\", 98765.432)}`);\n// Expected: \"98.765,43\"","lang":"typescript","description":"Demonstrates basic number formatting, currency handling, the `enforceMaskSign` option, and custom separators."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":">=2.0.0"},{"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.","message":"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`.","severity":"gotcha","affected_versions":">=1.0.0"},{"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)`.","message":"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.","severity":"gotcha","affected_versions":">=2.0.0"},{"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'`.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Change the import statement from `import { format } from 'number-format.js';` to `import format from 'number-format.js';`","cause":"Attempting to import the default `format` function as a named import in an ESM environment.","error":"TypeError: (0 , number_format_js_1.format) is not a function"},{"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`.","cause":"The library defaults a single non-digit symbol in the mask to be the decimal separator.","error":"Output '1234567,890' when expecting '1,234,567' with 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)`.","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.","error":"Prefix or suffix characters (e.g., 'USD ') are unexpectedly stripped or not appearing in the output."}],"ecosystem":"npm"}