numberparrot

numberparrot / Guides

numeral.js Alternative for Parsing Localized Numbers

numeral.js was the go to library for formatting and unformatting numbers. Its last release, 2.0.6, was published to npm in March 2017.

Where numeral.js struggles today

  • Locales are registered by hand. Only en is built in; other locales are separate definitions you load and select globally with numeral.locale().
  • Global state. The active locale is shared by the whole app, which makes mixed locale data (a CSV from Germany, a price from Brazil) awkward.
  • Silent wrong values. With the default locale, numeral("1.234,56").value() returns 1.23456.
  • No non-Latin digits and no Unicode minus sign.
example.ts
import numeral from "numeral";

numeral("1.234,56").value(); // 1.23456 with the default "en" locale
numeral("١٢٣").value();      // null

The replacement for unformatting

numberparrot takes the locale per call and reads its separators from Intl, so every locale your runtime supports works without registering anything:

example.ts
import { parse, parseCurrency } from "numberparrot";

parse("1.234,56", "pt-BR");             // 1234.56
parse("1.234,56", "de-DE");             // 1234.56
parse("(1,234.56)", "en-US");           // -1234.56
parse("15%", "en-US");                  // 0.15, same as numeral("15%").value()
parseCurrency("R$ 1.234,56", "pt-BR");  // { amount: 1234.56, currency: "BRL", ... }

Migration table

numeral.jsnumberparrot or the platform
numeral.locale("pt-br"); numeral(s).value()parse(s, "pt-BR")
numeral(s).value() on moneyparseCurrency(s, locale).amount
numeral(n).format("0,0.00")new Intl.NumberFormat(locale, { minimumFractionDigits: 2, maximumFractionDigits: 2 }).format(n)
numeral(n).format("$0,0.00")new Intl.NumberFormat(locale, { style: "currency", currency: "USD" }).format(n)
numeral(n).format("0%")new Intl.NumberFormat(locale, { style: "percent" }).format(n)

numberparrot only parses. For formatting, the built in Intl.NumberFormat already covers what numeral did, for every locale, with no library at all.

Other options

@internationalized/number from Adobe React Aria also parses with Intl data and is actively maintained. It needs the exact format options of the value (for example style: "currency" and the currency code) to read currency or percent strings. numberparrot is aimed at strings whose format you do not control, adds detect() for unknown locales and toMinorUnits for money.

Install

Terminal
npm install numberparrot

Zero dependencies, ESM and CommonJS, TypeScript types included. Works in Node.js 18+, Deno, Bun and browsers. Try it in the playground.

More guides