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