number-formatter

Lightweight, zero-dependency JavaScript number formatting library.

Features: thousands separators, currency, compact abbreviations (K/M/B/T), ordinals, file sizes, zero-padding, fixed decimals, percentages, rounding to a step, clamping, durations, and string parsing.

Links

• Demo & documentation: https://www.html-code-generator.com/javascript/number-formatter
• npm: https://www.npmjs.com/package/hcg-number-formatter
• GitHub: https://github.com/html-code-generator/hcg-number-formatter

Files

formatter.js      - UMD source (browser <script> tag or Node.js require)
demo.html         - Interactive browser demo
npm/
  index.js        - npm distribution (CommonJS)
  index.d.ts      - TypeScript type definitions
  usage.js        - Node.js usage examples

Browser Usage

<script src="formatter.js"></script>
<script>
  const { format, currency, compact, ordinal, fileSize, pad, fixed, percent, roundTo, clamp, duration, parse } = NumberFormatter;

  console.log(currency(1234.5));     // "$1,234.50"
  console.log(compact(1500000));     // "1.5M"
  console.log(ordinal(21));          // "21st"
</script>

Node.js Usage

npm install hcg-number-formatter

const { format, currency, compact, ordinal, fileSize, pad, fixed, percent, roundTo, clamp, duration, parse } = require('hcg-number-formatter');

// or ESM
import { format, currency, compact } from 'hcg-number-formatter';

---

API

format(n, options?)

Format a number with thousands separators.

Option	Type	Default	Description
decimals	number	auto	Number of decimal places
separator	string	','	Thousands separator
decimal	string	'.'	Decimal point character

format(1234567.89)                                // "1,234,567.89"
format(1234567, { decimals: 0 })                  // "1,234,567"
format(1234.5, { separator: '.', decimal: ',' })  // "1.234,5"
format(-9876543.21, { decimals: 2 })              // "-9,876,543.21"

---

currency(n, options?)

Format a number as currency.

Option	Type	Default	Description
symbol	string	'$'	Currency symbol
position	'before' | 'after'	'before'	Symbol placement
decimals	number	2	Decimal places
code	string	—	ISO 4217 code — auto-sets symbol and decimals
negativeStyle	'minus' | 'parens'	'minus'	How to show negative values
separator	string	','	Thousands separator

currency(1234.5)                                          // "$1,234.50"
currency(1234.5, { symbol: '€', position: 'after' })     // "1,234.50€"
currency(1234.5, { code: 'JPY' })                         // "¥1,235"
currency(1234.5, { code: 'EUR' })                         // "€1,234.50"
currency(-500, { negativeStyle: 'parens' })               // "($500.00)"

Supported ISO codes: USD, EUR, GBP, JPY, CNY, KRW, INR, BRL, CAD, AUD, CHF, MXN, SGD, HKD, SEK, NOK, DKK, PLN, THB, IDR, TRY, RUB, ZAR, AED, SAR, NZD

---

compact(n, options?)

Abbreviate large numbers with K/M/B/T suffixes.

Option	Type	Default	Description
precision	number	1	Decimal places in output
units	string[]	['','K','M','B','T']	Custom unit labels
threshold	number	1000	Minimum value to abbreviate

compact(999)                          // "999"
compact(1200)                         // "1.2K"
compact(1500000)                      // "1.5M"
compact(2000000000)                   // "2B"
compact(1200, { precision: 2 })       // "1.20K"
compact(-3400000)                     // "-3.4M"
compact(1500, { threshold: 10000 })   // "1500"

---

ordinal(n)

Convert a number to its ordinal string.

ordinal(1)    // "1st"
ordinal(2)    // "2nd"
ordinal(3)    // "3rd"
ordinal(4)    // "4th"
ordinal(11)   // "11th"
ordinal(12)   // "12th"
ordinal(21)   // "21st"
ordinal(101)  // "101st"

---

fileSize(n, options?)

Format a byte count as a human-readable file size.

Option	Type	Default	Description
standard	'iec' | 'si'	'iec'	iec = KiB/MiB (base-1024), si = KB/MB (base-1000)
decimals	number	2	Decimal places

fileSize(0)                                // "0 Bytes"
fileSize(1024)                             // "1 KiB"
fileSize(1500000)                          // "1.43 MiB"
fileSize(1073741824)                       // "1 GiB"
fileSize(1500000, { standard: 'si' })      // "1.5 MB"
fileSize(1500000, { decimals: 1 })         // "1.4 MiB"

---

pad(n, options?)

Pad a number with leading characters to a fixed length.

Option	Type	Default	Description
length	number	2	Total output length
char	string	'0'	Pad character

pad(5, { length: 3 })          // "005"
pad(42, { length: 5 })         // "00042"
pad(7, { length: 4, char: '*' }) // "***7"
pad(1000, { length: 3 })       // "1000"  (no truncation)

---

fixed(n, options?)

Format a number to an exact number of decimal places.

Option	Type	Default	Description
decimals	number	2	Number of decimal places

fixed(3.14159, { decimals: 2 })   // "3.14"
fixed(3.1, { decimals: 4 })       // "3.1000"
fixed(100, { decimals: 2 })       // "100.00"

---

percent(n, options?)

Format a number as a percentage.

Option	Type	Default	Description
decimals	number	trim	Decimal places (default trims trailing zeros)
scale	boolean	true	Multiply by 100 first; set false if the value is already a percentage
space	boolean	false	Insert a space before the %
separator	string	','	Thousands separator
decimal	string	'.'	Decimal point character

percent(0.1234)                       // "12.34%"
percent(0.1234, { decimals: 1 })      // "12.3%"
percent(1)                            // "100%"
percent(0.05, { decimals: 2 })        // "5.00%"
percent(25, { scale: false })         // "25%"
percent(-0.075)                       // "-7.5%"
percent(0.3333, { decimals: 1, space: true })  // "33.3 %"

---

roundTo(n, options?)

Round a number to a nearest step or to a number of decimal places. Returns a number, not a string.

Option	Type	Default	Description
nearest	number	—	Round to the nearest multiple of this step
decimals	number	0	Round to this many decimals (ignored when nearest is set)
mode	'round' | 'floor' | 'ceil'	'round'	Rounding direction

roundTo(1234, { nearest: 50 })             // 1250
roundTo(1234, { nearest: 100 })            // 1200
roundTo(2.345, { decimals: 1 })            // 2.3
roundTo(1234, { nearest: 50, mode: 'floor' })  // 1200
roundTo(1201, { nearest: 50, mode: 'ceil' })   // 1250
roundTo(0.07, { nearest: 0.05 })           // 0.05

---

clamp(n, min?, max?)

Constrain a number to the inclusive range [min, max]. Either bound may be omitted. Returns a number.

clamp(15, 0, 10)            // 10
clamp(-5, 0, 10)            // 0
clamp(7, 0, 10)             // 7
clamp(3, 5)                 // 5   (min only)
clamp(100, undefined, 50)   // 50  (max only)

---

duration(seconds, options?)

Format a count of seconds as a human-readable duration.

Option	Type	Default	Description
style	'short' | 'clock' | 'long'	'short'	Output style
units	string[]	['d','h','m','s']	Which units to use

duration(3661)                          // "1h 1m 1s"
duration(90)                            // "1m 30s"
duration(45)                            // "45s"
duration(3661, { style: 'clock' })      // "1:01:01"
duration(90, { style: 'clock' })        // "1:30"
duration(3661, { style: 'long' })       // "1 hour 1 minute 1 second"
duration(7200, { style: 'long' })       // "2 hours"
duration(93784)                         // "1d 2h 3m 4s"
duration(125, { units: ['m', 's'] })    // "2m 5s"

---

parse(str)

Parse a formatted number string back to a number.

Strips currency symbols, grouping separators, and whitespace. Parentheses are treated as negative. Defaults to US style; European 1.234,56 is auto-detected, or pass { separator, decimal } for any locale.

parse('$1,234.56')                  // 1234.56
parse('€9,999.99')                  // 9999.99
parse('1,000,000')                  // 1000000
parse('($500.00)')                  // -500
parse('-250.75')                    // -250.75
parse('1.234,56', { decimal: ',' }) // 1234.56  (European)
parse('abc')                        // NaN

---

Development

formatter.js is the source of truth. After editing it, sync the npm copy:

npm run sync     # copies formatter.js -> npm/index.js

Testing

A zero-dependency Node test suite (no Jest/Vitest needed) covers every function and the known edge cases:

npm test         # runs node test.js

---

License

MIT — HTML Code Generator