numberstring

Number One Way to Makes Words from Numbers

Transform any number into beautiful words. From 42 to "forty-two", from 1000000 to "one million". Supports 22 languages, ordinals, currency, Roman numerals, Egyptian hieroglyphs, Babylonian cuneiform, circled digits, and more!

Try it: numberstring.netlify.app — type a number, see it in 22 languages. Runs entirely in your browser.

Why numberstring?

Zero dependencies - Lightweight and fast
22 languages - English, Spanish, French, German, Danish, Chinese, Hindi, Russian, Portuguese, Japanese, Korean, Arabic, Italian, Dutch, Turkish, Polish, Swedish, Indonesian, Thai, Norwegian, Finnish, Icelandic
Huge range - Supports 0 to decillions (10^36) with BigInt
Feature-rich - Ordinals, decimals, currency, fractions, years, phone numbers, NATO/ICAO radio numerals, Morse code, scientific notation, binary/hex, byte sizes, clock faces
Roman numerals - Classic and vinculum notation to 3,999,999,999
Ancient and alternative numerals - Egyptian hieroglyphs, Babylonian cuneiform, Greek letters, Chinese/Japanese financial forms
Unicode digit styles - ④② ⁴² ４２ 𝟜𝟚 4️⃣2️⃣ ⠼⠙⠃
Forgiving input - Integers, negatives, decimals, numeric strings, BigInt. It just works
Well tested - 780+ tests with 90%+ coverage, per-language spot checks, and a fuzz suite proving nothing ever throws
Modern ES modules - Tree-shakeable, with bundled TypeScript declarations

Installation

npm install numberstring

Quick Start

import numberstring from 'numberstring';

numberstring(42);                    // 'forty-two'
numberstring(1000000);               // 'one million'
numberstring(10n ** 18n);            // 'one quintillion' (BigInt!)
numberstring(-3.14);                 // 'negative three point one four'
numberstring('1000');                // 'one thousand'
numberstring(42, { lang: 'es' });    // 'cuarenta y dos'
numberstring(123, { and: true });    // 'one hundred and twenty-three'
numberstring(123, { cap: 'title' }); // 'One Hundred Twenty-Three'

API Reference

Everything at a glance. Every function returns a string, or false when the input cannot be converted.

Function	Example	Result
`numberstring(n, opt)`	`numberstring(-3.14)`	`negative three point one four`
`toWords(n, { lang })`	`toWords(42, { lang: 'es' })`	`cuarenta y dos`
`ordinal(n)`	`ordinal(21)`	`twenty-first`
`nth(n)`	`nth(22)`	`22nd`
`decimal(n)`	`decimal(3.14)`	`three point one four`
`fraction(a, b)`	`fraction(3, 4)`	`three quarters`
`percent(n)`	`percent(50)`	`fifty percent`
`currency(s)`	`currency('$1.50')`	`one dollar and fifty cents`
`year(n)`	`year(1984)`	`nineteen eighty-four`
`telephone(s, { oh })`	`telephone(8675309, { oh: true })`	`eight six seven five three oh nine`
`nato(n)` / `icao` / `military`	`nato(1984)`	`wun niner ait fower`
`morse(n)`	`morse(42)`	`....- ..---`
`compact(n)`	`compact(1500000)`	`1.5M`
`scientific(n)`	`scientific(1984)`	`1.984 × 10³`
`comma(n)`	`comma(1234567)`	`1,234,567`
`binary(n)` / `octal` / `hex` / `radix(n, base)`	`hex(255, { prefix: true })`	`0xff`
`bytes(n)` / `bits(n)`	`bytes(1536)`	`1.5 KB`
`roman(n)`	`roman(1999)`	`MCMXCIX`
`greek(n)`	`greek(42)`	`μβʹ`
`egyptian(n)`	`egyptian(42)`	`𓎆𓎆𓎆𓎆𓏺𓏺`
`babylonian(n)`	`babylonian(42)`	`𒌋𒌋𒌋𒌋𒁹𒁹`
`fancy(n, style)`	`fancy(42, 'doublestruck')`	`𝟜𝟚`
`clock(time)`	`clock('3:30')`	`🕞`
`parse(words)`	`parse('forty-two')`	`42`
`negative(n)`	`negative(-42)`	`negative forty-two`

Constants: CAP_STYLES (casing names for cap), FANCY_STYLE_NAMES (styles for fancy). Each language is also a named export (spanish, french, ... see below).

Core Functions

`numberstring(n, [options])`

Convert a number to words. Forgiving by design: accepts integers, negatives, decimals, numeric strings, and BigInt, and honors lang. Returns false for anything it cannot say.

numberstring(42);                    // 'forty-two'
numberstring(-7);                    // 'negative seven'
numberstring(2.5);                   // 'two point five'
numberstring('1000000');             // 'one million'
numberstring(42, { lang: 'fr' });    // 'quarante-deux'
numberstring(100, { cap: 'title' }); // 'One Hundred'
numberstring(100, { punc: '!' });    // 'one hundred!'
numberstring('abc');                 // false

Every word-producing function takes cap, and it does more than capitalize:

numberstring(123, { cap: 'camel' });     // 'oneHundredTwentyThree'
numberstring(123, { cap: 'pascal' });    // 'OneHundredTwentyThree'
numberstring(123, { cap: 'snake' });     // 'one_hundred_twenty_three'
numberstring(123, { cap: 'kebab' });     // 'one-hundred-twenty-three'
numberstring(123, { cap: 'constant' });  // 'ONE_HUNDRED_TWENTY_THREE'
numberstring(123, { cap: 'dot' });       // 'one.hundred.twenty.three'
numberstring(123, { cap: 'sentence' });  // 'One hundred twenty-three'

Negatives and decimals are English-only; with another lang they return false rather than falling back to English. Pass and: true for British style ("one hundred and one", "one thousand and one").

`ordinal(n, [options])`

Convert to ordinal words (first, second, etc.).

import { ordinal } from 'numberstring';

ordinal(1);   // 'first'
ordinal(2);   // 'second'
ordinal(21);  // 'twenty-first'
ordinal(100); // 'one hundredth'

`decimal(n, [options])`

Convert decimal numbers to words.

import { decimal } from 'numberstring';

decimal(3.14);   // 'three point one four'
decimal(0.5);    // 'zero point five'
decimal(-3.14);  // 'negative three point one four'

`currency(amount, [options])`

Convert currency amounts to words.

import { currency } from 'numberstring';

currency('$123.45');  // 'one hundred twenty-three dollars and forty-five cents'
currency('€50');      // 'fifty euros'
currency('£1.01');    // 'one pound and one penny'
currency('¥1000');    // 'one thousand yen'
currency('₹100.50');  // 'one hundred rupees and fifty paise'

Supported currencies: $ € £ ¥ ₹ 元 (USD, EUR, GBP, JPY, INR, CNY)

`roman(n, [options])`

Convert to Roman numerals. Above 3999, vinculum notation puts a bar over a group to multiply it by 1000 (two bars for a million), reaching 3,999,999,999.

import { roman } from 'numberstring';

roman(42);                   // 'XLII'
roman(1999);                 // 'MCMXCIX'
roman(4, { lower: true });   // 'iv'
roman(4000);                 // 'I̅V̅'
roman(8675309);              // 'V̿I̿I̿I̿D̅C̅L̅X̅X̅V̅CCCIX'

`parse(str)`

Parse English words back to a number.

import { parse } from 'numberstring';

parse('forty-two');        // 42
parse('one thousand');     // 1000
parse('one quintillion');  // 1000000000000000000n (BigInt)

`nth(n)`

Numeric ordinal suffix.

import { nth } from 'numberstring';

nth(1);    // '1st'
nth(22);   // '22nd'
nth(113);  // '113th'

`compact(n, [options])`

Compact notation.

import { compact } from 'numberstring';

compact(1500);                     // '1.5K'
compact(2300000000);               // '2.3B'
compact(999950);                   // '1M'
compact(1234567, { digits: 2 });   // '1.23M'
compact(1500000, { long: true });  // '1.5 million'

`fancy(n, [style])`

Digits in a Unicode style: circled (default), superscript, subscript, fullwidth, bold, doublestruck, sans, monospace, keycap (alias emoji), clock, braille.

import { fancy } from 'numberstring';

fancy(42);                   // '④②'
fancy(42, 'superscript');    // '⁴²'
fancy(42, 'doublestruck');   // '𝟜𝟚'
fancy(42, 'keycap');         // '4️⃣2️⃣'
fancy(814, 'clock');         // '🕗🕐🕓'
fancy(-3.5, 'braille');      // '⠼⠤⠉⠨⠑'

Ancient and Alternative Numerals

All render with Unicode glyphs, so they need a font that covers the block (most modern systems do).

import { egyptian, babylonian, greek } from 'numberstring';

egyptian(42);     // '𓎆𓎆𓎆𓎆𓏺𓏺'       additive, 1 to 9,999,999
babylonian(42);   // '𒌋𒌋𒌋𒌋𒁹𒁹'       base 60, places separated by spaces
babylonian(3600); // '𒁹 𒑊 𒑊'
greek(42);        // 'μβʹ'             Ionic letters, 1 to 9999
greek(1999);      // '͵αϡϟθʹ'

Chinese and Japanese also have the anti-fraud financial forms used on cheques:

import { chinese, japanese } from 'numberstring';

chinese(1001, { formal: true });   // '壹仟零壹'  (大写)
japanese(1001, { formal: true });  // '壱千壱'    (大字)

Utility Functions

`negative(n, [options])`

Handle negative numbers.

import { negative } from 'numberstring';

negative(-42);  // 'negative forty-two'
negative(42);   // 'forty-two'

`fraction(numerator, denominator, [options])`

Convert fractions to words.

import { fraction } from 'numberstring';

fraction(1, 2);  // 'one half'
fraction(3, 4);  // 'three quarters'
fraction(5, 8);  // 'five eighths'

`year(y, [options])`

Convert years to spoken form.

import { year } from 'numberstring';

year(1984);     // 'nineteen eighty-four'
year(2000);     // 'two thousand'
year(2024);     // 'twenty twenty-four'
year(8675309);  // 'eight million six hundred seventy-five thousand three hundred nine'

`telephone(phone, [options])`

Convert phone numbers to words.

import { telephone } from 'numberstring';

telephone('555-1234');              // 'five five five one two three four'
telephone(8675309);                 // 'eight six seven five three zero nine'
telephone(8675309, { oh: true });   // 'eight six seven five three oh nine'

`nato(n, [options])`

ICAO / NATO radiotelephony numerals, the way pilots and air traffic control read numbers. Also exported as icao and military.

import { nato } from 'numberstring';

nato(1984);                   // 'wun niner ait fower'
nato(2500);                   // 'too tousand fife hundred'
nato('121.5');                // 'wun too wun decimal fife'
nato(2500, { digits: true }); // 'too fife zero zero'

`morse(n)`

International Morse code for the digits.

import { morse } from 'numberstring';

morse(42);   // '....- ..---'
morse(3.1);  // '...-- .-.-.- .----'

`scientific(n, [options])`

Scientific notation with an exact decimal mantissa. Formats: unicode (default), caret, e, words.

import { scientific } from 'numberstring';

scientific(1984);                        // '1.984 × 10³'
scientific(0.00042);                     // '4.2 × 10⁻⁴'
scientific(1984, { format: 'e' });       // '1.984e3'
scientific(1984, { digits: 3 });         // '1.98 × 10³'
scientific(1984, { format: 'words' });   // 'one point nine eight four times ten to the third'

`binary(n)`, `octal(n)`, `hex(n)`, `radix(n, base)`

Integers in other bases, 2 to 36.

import { binary, hex, radix } from 'numberstring';

binary(42);                                      // '101010'
hex(255, { prefix: true, upper: true });         // '0xFF'
binary(5, { pad: 8 });                           // '00000101'
radix(42, 36);                                   // '16'

`bytes(n, [options])` and `bits(n, [options])`

Human-readable data sizes. Bytes use KB/KiB, bits use bandwidth-style kb/Mb.

import { bytes, bits } from 'numberstring';

bytes(1536);                     // '1.5 KB'
bytes(1536, { binary: true });   // '1.5 KiB'
bytes(1536, { long: true });     // 'one point five kilobytes'
bits(1500000);                   // '1.5 Mb'
bits(1500000, { long: true });   // 'one point five megabits'

`clock(time)`

Clock-face emoji for an hour or an H:MM time, rounded to the half hour.

import { clock } from 'numberstring';

clock(3);        // '🕒'
clock('3:30');   // '🕞'
clock(15);       // '🕒'

`percent(pct, [options])`

Convert percentages to words.

import { percent } from 'numberstring';

percent(50);     // 'fifty percent'
percent('25%');  // 'twenty-five percent'
percent(3.5);    // 'three point five percent'

`comma(n)`

Format a number with comma separators.

import { comma } from 'numberstring';

comma(1234567);     // '1,234,567'
comma(1234567.89);  // '1,234,567.89'

Multi-Language Support

numberstring supports 22 languages! Each language is in a separate file for easy tree-shaking.

import { toWords } from 'numberstring';

// Using toWords with lang option
toWords(42, { lang: 'es' });  // 'cuarenta y dos'
toWords(42, { lang: 'fr' });  // 'quarante-deux'
toWords(42, { lang: 'de' });  // 'zweiundvierzig'
toWords(42, { lang: 'da' });  // 'toogfyrre'
toWords(42, { lang: 'zh' });  // '四十二'
toWords(42, { lang: 'hi' });  // 'बयालीस'
toWords(42, { lang: 'ru' });  // 'сорок два'
toWords(42, { lang: 'pt' });  // 'quarenta e dois'
toWords(42, { lang: 'ja' });  // '四十二'
toWords(42, { lang: 'ko' });  // '사십이'
toWords(42, { lang: 'ar' });  // 'اثنان وأربعون'
toWords(42, { lang: 'it' });  // 'quarantadue'
toWords(42, { lang: 'nl' });  // 'tweeënveertig'
toWords(42, { lang: 'tr' });  // 'kırk iki'
toWords(42, { lang: 'pl' });  // 'czterdzieści dwa'
toWords(42, { lang: 'sv' });  // 'fyrtiotvå'
toWords(42, { lang: 'id' });  // 'empat puluh dua'
toWords(42, { lang: 'th' });  // 'สี่สิบสอง'
toWords(42, { lang: 'no' });  // 'førtito'
toWords(42, { lang: 'fi' });  // 'neljäkymmentäkaksi'
toWords(42, { lang: 'is' });  // 'fjörutíu og tveir'

Supported Languages

Code	Language	Example (42)
`en`	English	forty-two
`es`	Spanish	cuarenta y dos
`fr`	French	quarante-deux
`de`	German	zweiundvierzig
`da`	Danish	toogfyrre
`zh`	Chinese	四十二
`hi`	Hindi	बयालीस
`ru`	Russian	сорок два
`pt`	Portuguese	quarenta e dois
`ja`	Japanese	四十二
`ko`	Korean	사십이
`ar`	Arabic	اثنان وأربعون
`it`	Italian	quarantadue
`nl`	Dutch	tweeënveertig
`tr`	Turkish	kırk iki
`pl`	Polish	czterdzieści dwa
`sv`	Swedish	fyrtiotvå
`id`	Indonesian	empat puluh dua
`th`	Thai	สี่สิบสอง
`no`	Norwegian	førtito
`fi`	Finnish	neljäkymmentäkaksi
`is`	Icelandic	fjörutíu og tveir

Direct language exports

Each language is also exported by name for tree-shaking: spanish, french, german, danish, chinese, hindi, russian, portuguese, japanese, korean, arabic, italian, dutch, turkish, polish, swedish, indonesian, thai, norwegian, finnish, icelandic. They take a non-negative integer and return the cardinal words. Use toWords() or numberstring() with lang when you want cap and the other options.

import { french, japanese } from 'numberstring';

french(1984);                        // 'mille neuf cent quatre-vingt-quatre'
japanese(1984, { formal: true });    // '壱千九百八拾四'

Adding a New Language

Languages are modular! To add a new language:

Create languages/xx.js following the pattern in languages/en.js
Export your conversion function
Add to languages/index.js, re-export it from index.js, and add it to the toWords switch
Add a row to the table in test/languages.test.js and a named export in index.d.ts
Submit a PR!

Options

Option	Type	Description
`cap`	`string`	Casing: `'title'`, `'upper'`, `'lower'`, `'sentence'`, `'camel'`, `'pascal'`, `'snake'`, `'kebab'`, `'constant'`, `'dot'`
`punc`	`string`	Punctuation: `'!'`, `'?'`, or `'.'`
`lang`	`string`	Language code for `numberstring()` and `toWords()`
`point`	`string`	Word for decimal point (default: `'point'`)
`and`	`boolean`	British style: `one hundred and one`
`formal`	`boolean`	Chinese/Japanese financial numerals
`lower`	`boolean`	Lowercase Roman numerals

Supported Scales

Scale	Power	Example
Ones	10^0	`five`
Thousands	10^3	`five thousand`
Millions	10^6	`five million`
Billions	10^9	`five billion`
Trillions	10^12	`five trillion`
Quadrillions	10^15	`five quadrillion`
Quintillions	10^18	`five quintillion` (BigInt)
Sextillions	10^21	`five sextillion` (BigInt)
Septillions	10^24	`five septillion` (BigInt)
Octillions	10^27	`five octillion` (BigInt)
Nonillions	10^30	`five nonillion` (BigInt)
Decillions	10^33	`five decillion` (BigInt)

Playground

The playground at numberstring.netlify.app is a single static page in site/ that imports the library directly. No framework, no backend.

npm run site     # stage the library into site/lib and serve at http://localhost:8080

The former Express REST server lives in archive/server/, unmaintained.

Development

npm install        # Install dependencies
npm test           # Run tests
npm run lint       # Run linter
npm run test:coverage  # Test with coverage
npm run site           # Run the playground locally

Contributing

Please read CONTRIBUTING.md for details on the process for submitting pull requests.

We especially welcome contributions for new languages! See the Contributing guide for details.

Versioning

This project uses Semantic Versioning 2.0.

Requirements

Node.js 18+
ES modules (import/export)

License

MIT

Name		Name	Last commit message	Last commit date
.github		.github
archive		archive
languages		languages
scripts		scripts
site		site
test		test
.gitignore		.gitignore
.npmignore		.npmignore
AGENTS.md		AGENTS.md
CHANGELOG.md		CHANGELOG.md
CLAUDE.md		CLAUDE.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
demo.js		demo.js
eslint.config.js		eslint.config.js
index.d.ts		index.d.ts
index.js		index.js
netlify.toml		netlify.toml
numerals.js		numerals.js
package-lock.json		package-lock.json
package.json		package.json
vitest.config.js		vitest.config.js

Latest commit

History

Folders and files

Repository files navigation

numberstring

Why numberstring?

Installation

Quick Start

API Reference

Core Functions

numberstring(n, [options])

ordinal(n, [options])

decimal(n, [options])

currency(amount, [options])

roman(n, [options])

parse(str)

nth(n)

compact(n, [options])

fancy(n, [style])

Ancient and Alternative Numerals

Utility Functions

negative(n, [options])

fraction(numerator, denominator, [options])

year(y, [options])

telephone(phone, [options])

nato(n, [options])

morse(n)

scientific(n, [options])

binary(n), octal(n), hex(n), radix(n, base)

bytes(n, [options]) and bits(n, [options])

clock(time)

percent(pct, [options])

comma(n)

Multi-Language Support

Supported Languages

Direct language exports

Adding a New Language

Options

Supported Scales

Playground

Development

Contributing

Versioning

Requirements

License

# " "

About

Topics

Resources

Contributing

Stars

Watchers

Forks

Releases

Packages

Used by

Contributors

Languages

`numberstring(n, [options])`

`ordinal(n, [options])`

`decimal(n, [options])`

`currency(amount, [options])`

`roman(n, [options])`

`parse(str)`

`nth(n)`

`compact(n, [options])`

`fancy(n, [style])`

`negative(n, [options])`

`fraction(numerator, denominator, [options])`

`year(y, [options])`

`telephone(phone, [options])`

`nato(n, [options])`

`morse(n)`

`scientific(n, [options])`

`binary(n)`, `octal(n)`, `hex(n)`, `radix(n, base)`

`bytes(n, [options])` and `bits(n, [options])`

`clock(time)`

`percent(pct, [options])`

`comma(n)`