Numeral.js

Numeral.js is a lightweight JavaScript library for formatting and manipulating numbers, currency, percentages, byte sizes, and time values using compact, spreadsheet-style format strings like ‘0,0.00’ or ‘$0,0’. It wraps a number in a chainable Numeral object exposing arithmetic helpers (add, subtract, multiply, divide) with built-in floating-point correction, alongside a pluggable format and locale registry so consumers can register only the formats and locales they need.

Originally released in 2012 and still widely used (millions of weekly npm downloads), it ships as a dependency-free UMD module that works in Node, browsers, and AMD/CommonJS bundlers alike, with 30+ community-contributed locale files for internationalized currency and number formatting.

What You Get

• Format numbers as currency, percentages, byte sizes, ordinals, and time using compact format strings (‘$0,0.00’, ‘0%’, ‘0b’)
• Chainable arithmetic (add/subtract/multiply/divide) with built-in floating-point correction
• 30+ bundled locale files for internationalized currency symbols, thousands/decimal separators, and abbreviations
• A numeral.register() API for defining custom formats or locales beyond the bundled set
• Zero runtime dependencies, shipped as a UMD bundle compatible with Node, browsers, AMD, and CommonJS

Common Use Cases

• Formatting dashboard/report numbers (revenue, percentages, file sizes) for display without hand-writing Intl.NumberFormat options
• Localizing currency and number output for international users via numeral.locale()
• Safely summing/aggregating floating-point money values without cent-rounding drift
• Converting between raw bytes and human-readable file sizes (e.g. ‘1024000’ to ‘1.02MB’)

Under The Hood

Architecture - numeral.js is a single UMD module (src/numeral.js, ~700 lines) built around a Numeral constructor that wraps an _input/_value pair. A registry pattern (numeral.register('format'|'locale', name, definition)) lets formats (currency, percentage, bytes, ordinal, time, bps, exponential) and locales register their own regex-based parse (unformat) and render (format) functions into shared formats/locales objects; numeral(input) iterates registered formats to unformat a string into a value, and .format(str) iterates them again to match the format string against each format’s regex and delegate rendering. This plugin-style design is what enables the project’s “custom build with only certain formats” story referenced in its changelog.

Tech Stack - Plain ES5 JavaScript with no runtime dependencies; the UMD wrapper (define/module.exports/global.numeral) supports AMD, CommonJS, and global-script consumption without a build step for consumers. The project’s own dev tooling is dated: Grunt (Gruntfile.js) drives jshint, uglify, and karma browser tests via Sauce Labs, alongside bower.json/component.json for legacy front-end package managers - reflecting its 2012-era origin rather than a modern toolchain.

Code Quality - 42 test files under tests/ (a large core suite plus one file per locale) written with Mocha/Chai, giving solid coverage of format/locale edge cases, especially around floating-point correction and locale-specific delimiters. The core module itself uses classic var-based ES5 with no TypeScript types and fairly dense regex-driven parsing logic in the unformat/validate paths; there’s no active CI badge (the Travis links are defunct) and commit activity is low, though the repo still receives occasional maintenance pushes.

API Design - The numeral(value).format('0,0.00') pattern is terse and immediately familiar to anyone who has used spreadsheet number-format codes, which lowers the barrier for common formatting tasks. Chainable arithmetic methods (add/subtract/multiply/divide) cover everyday numeric operations with built-in floating-point correction. Locale switching and custom format registration are powerful but rely on the external numeraljs.com site for full documentation rather than inline JSDoc or an in-repo docs folder, so deeper API discovery leans on the website link in the README.