@codeshumon/number-to-words

Convert Number to Words | Number to Words Converter Including Currency Format ➡️🔠

Convert numbers to words with currency formatting for 130+ countries. Perfect for invoices, checks, and financial applications.

Table of Contents

Features ✨
Installation 📦
Basic Usage 🔢
Advanced Usage 🛠️
API Reference & Options 📚
Supported Countries 🌎
TypeScript Support ✅
Benchmarks ⚡
Browser Compatibility 🌐
Contributing 🤝
License 📄

Features ✨

🔢 Convert numbers to words (e.g., 123 → "One Hundred Twenty Three")
💰 Currency formatting for 130+ countries
🔣 Supports both integer and decimal numbers
🔧 TypeScript and JavaScript compatible
📦 Lightweight (zero dependencies)
🌍 Supports negative and large numbers up to Trillion

Installation 📦

npm install @codeshumon/number-to-words

or

yarn add @codeshumon/number-to-words

Basic Usage 🔢 Convert Numbers to Words (Node.js CommonJS - main field)

const { numberToWords } = require('@codeshumon/number-to-words');

console.log(numberToWords(125.55));
// Output: "One Hundred Twenty Five and Point Five Five"

console.log(numberToWords(588532654484815));
// Output: "Five Hundred Eighty Eight Trillion Five Hundred Thirty Two Billion Six Hundred Fifty Four Million Four Hundred Eighty Four Thousand Eight Hundred Fifteen"

Convert Number to Currency Words 💰

const { numberToCurrencyWords } = require('@codeshumon/number-to-words');

// US Dollars
console.log(numberToCurrencyWords(1234.56, 'US'));
// "One Thousand Two Hundred Thirty Four Dollars and Fifty Six Cents Only"

// British Pounds
console.log(numberToCurrencyWords(789.12, 'GB'));
// "Seven Hundred Eighty Nine Pounds and Twelve Pence Only"

// Indian Rupees
console.log(numberToCurrencyWords(4567.89, 'IN'));
// "Four Thousand Five Hundred Sixty Seven Rupees and Eighty Nine Paise Only"

ES Module Usage (via module field)

import { numberToWords, numberToCurrencyWords } from '@codeshumon/number-to-words';

console.log(numberToWords(2023));
// Output: "Two Thousand Twenty Three"

console.log(numberToCurrencyWords(2500.75, 'US'));
// Output: "Two Thousand Five Hundred Dollars and Seventy Five Cents Only"

Browser Usage 🌐 (via CDN using browser field) Use Directly in HTML Include the script in your HTML:

<script src="https://unpkg.com/@codeshumon/number-to-words"></script>

Then, you can access the functions globally:

const { numberToWords, numberToCurrencyWords } = window.NumberToWords;

console.log(numberToWords(999.99));
// Output: "Nine Hundred Ninety Nine and Point Nine Nine"

console.log(numberToCurrencyWords(999.99, 'US'));
// Output: "Nine Hundred Ninety Nine Dollars and Ninety Nine Cents Only"

Advanced Usage 🛠️ Handling Negative Numbers

numberToCurrencyWords(-100.50, 'US');
// "Negative One Hundred Dollars and Fifty Cents Only"

Large Number Support

numberToWords(1000000000000);
// "One Trillion"

Advanced numberToWords Examples

const { numberToWords } = require('@codeshumon/number-to-words');

console.log(numberToWords(652222225.52226));
// Output: "Six Hundred Fifty-two Million, Two Hundred Twenty-two Thousand, Two Hundred Twenty-five Point Five Two"

console.log(numberToWords('4322222225.52226', { noHypen: true }));
// Output: "Four Billion, Three Hundred Twenty Two Million, Two Hundred Twenty Two Thousand, Two Hundred Twenty Five Point Five Two"

console.log(numberToWords('4322222225.52226', { noComa: true }));
// Output: "Four Billion Three Hundred Twenty-two Million Two Hundred Twenty-two Thousand Two Hundred Twenty-five Point Five Two"

console.log(numberToWords(2522222225.52226, {isAnd : true }));
// Output: "Two Billion and Five Hundred Twenty-two Million and Two Hundred Twenty-two Thousand and Two Hundred Twenty-five Point Five Two"

console.log(numberToWords('9222222225.8226', {titleCase : true}));
// Output: "Nine Billion, Two Hundred Twenty-Two Million, Two Hundred Twenty-Two Thousand, Two Hundred Twenty-Five Point Eight Two"

console.log(numberToWords(4022222225.6226, { titleCase : true, isAnd : true, noHypen: true }));
// Output: "Four Billion and Twenty Two Million and Two Hundred Twenty Two Thousand and Two Hundred Twenty Five Point Six Two"

Advanced numberToCurrencyWords Examples

const { numberToCurrencyWords } = require('@codeshumon/number-to-words');

// Default (assuming 'US' if no currency provided or unrecognized)
console.log(numberToCurrencyWords('115255500015.58780'));
// Output: "One Hundred Fifteen Billion, Two Hundred Fifty-five Million, Five Hundred Thousand, Fifteen Dollars and Fifty-nine Cents only"

console.log(numberToCurrencyWords('5552111111115.2500', 'GB',));
// Output: "Five Trillion, Five Hundred Fifty-two Billion, One Hundred Eleven Million, One Hundred Eleven Thousand, One Hundred Fifteen Pounds and Twenty-five Pence only"

console.log(numberToCurrencyWords('5552111111115.5500', 'GB', {noHypen: true}));
// Output: "Five Trillion, Five Hundred Fifty Two Billion, One Hundred Eleven Million, One Hundred Eleven Thousand, One Hundred Fifteen Pounds and Fifty Five Pence only"

console.log(numberToCurrencyWords('5552111111115.5500', 'GB', {noComa: true}));
// Output: "Five Trillion Five Hundred Fifty-two Billion One Hundred Eleven Million One Hundred Eleven Thousand One Hundred Fifteen Pounds and Fifty-five Pence only"

console.log(numberToCurrencyWords(5552111111115.6500, 'GB', {isAnd : true }));
// Output: "Five Trillion and Five Hundred Fifty-two Billion and One Hundred Eleven Million and One Hundred Eleven Thousand and One Hundred Fifteen Pounds and Sixty-five Pence only"

console.log(numberToCurrencyWords(5552111111115.9500, 'GB', {titleCase : true}));
// Output: "Five Trillion, Five Hundred Fifty-Two Billion, One Hundred Eleven Million, One Hundred Eleven Thousand, One Hundred Fifteen Pounds and Ninety-Five Pence only"

console.log(numberToCurrencyWords(5552111111115.750, 'GB', { titleCase : true, isAnd : true, noHypen: true }));
// Output: "Five Trillion and Five Hundred Fifty Two Billion and One Hundred Eleven Million and One Hundred Eleven Thousand and One Hundred Fifteen Pounds and Seventy Five Pence only"

ES Module Usage (via module field)

import { numberToWords, numberToCurrencyWords } from '@codeshumon/number-to-words';

console.log(numberToWords(2023));
// Output: "Two Thousand Twenty Three"

console.log(numberToCurrencyWords(2500.75, 'US'));
// Output: "Two Thousand Five Hundred Dollars and Seventy Five Cents Only"

console.log(numberToWords(652222225.52226));
// Output: "Six Hundred Fifty-two Million, Two Hundred Twenty-two Thousand, Two Hundred Twenty-five Point Five Two"

console.log(numberToCurrencyWords('5552111111115.2500', 'GB',));
// Output: "Five Trillion, Five Hundred Fifty-two Billion, One Hundred Eleven Million, One Hundred Eleven Thousand, One Hundred Fifteen Pounds and Twenty-five Pence only"

Browser Usage 🌐 (via CDN using browser field) Use Directly in HTML

Include the script in your HTML:

<script src="https://unpkg.com/@codeshumon/number-to-words"></script>

Then, you can access the functions globally:

const { numberToWords, numberToCurrencyWords } = window.NumberToWords;

console.log(numberToWords(999.99));
// Output: "Nine Hundred Ninety Nine and Point Nine Nine"

console.log(numberToCurrencyWords(999.99, 'US'));
// Output: "Nine Hundred Ninety Nine Dollars and Ninety Nine Cents Only"

console.log(numberToCurrencyWords('115255500015.58780'));
// Output: "One Hundred Fifteen Billion, Two Hundred Fifty-five Million, Five Hundred Thousand, Fifteen Dollars and Fifty-nine Cents only"

console.log(numberToCurrencyWords('5552111111115.2500', 'GB',));
// Output: "Five Trillion, Five Hundred Fifty-two Billion, One Hundred Eleven Million, One Hundred Eleven Thousand, One Hundred Fifteen Pounds and Twenty-five Pence only"

console.log(numberToCurrencyWords('5552111111115.5500', 'GB', {noHypen: true}));
// Output: "Five Trillion, Five Hundred Fifty Two Billion, One Hundred Eleven Million, One Hundred Eleven Thousand, One Hundred Fifteen Pounds and Fifty Five Pence only"

console.log(numberToCurrencyWords('5552111111115.5500', 'GB', {noComa: true}));
// Output: "Five Trillion Five Hundred Fifty-two Billion One Hundred Eleven Million One Hundred Eleven Thousand One Hundred Fifteen Pounds and Fifty-five Pence only"

console.log(numberToCurrencyWords(5552111111115.6500, 'GB', {isAnd : true }));
// Output: "Five Trillion and Five Hundred Fifty-two Billion and One Hundred Eleven Million and One Hundred Eleven Thousand and One Hundred Fifteen Pounds and Sixty-five Pence only"

console.log(numberToCurrencyWords(5552111111115.9500, 'GB', {titleCase : true}));
// Output: "Five Trillion, Five Hundred Fifty-Two Billion, One Hundred Eleven Million, One Hundred Eleven Thousand, One Hundred Fifteen Pounds and Ninety-Five Pence only"

console.log(numberToCurrencyWords(5552111111115.750, 'GB', { titleCase : true, isAnd : true, noHypen: true }));
// Output: "Five Trillion and Five Hundred Fifty Two Billion and One Hundred Eleven Million and One Hundred Eleven Thousand and One Hundred Fifteen Pounds and Seventy Five Pence only"

console.log(numberToWords(652222225.52226));
// Output: "Six Hundred Fifty-two Million, Two Hundred Twenty-two Thousand, Two Hundred Twenty-five Point Five Two"

console.log(numberToWords('4322222225.52226', { noHypen: true }));
// Output: "Four Billion, Three Hundred Twenty Two Million, Two Hundred Twenty Two Thousand, Two Hundred Twenty Five Point Five Two"

console.log(numberToWords('4322222225.52226', { noComa: true }));
// Output: "Four Billion Three Hundred Twenty-two Million Two Hundred Twenty-two Thousand Two Hundred Twenty-five Point Five Two"

console.log(numberToWords(2522222225.52226, {isAnd : true }));
// Output: "Two Billion and Five Hundred Twenty-two Million and Two Hundred Twenty-two Thousand and Two Hundred Twenty-five Point Five Two"

console.log(numberToWords('9222222225.8226', {titleCase : true}));
// Output: "Nine Billion, Two Hundred Twenty-Two Million, Two Hundred Twenty-Two Thousand, Two Hundred Twenty-Five Point Eight Two"

console.log(numberToWords(4022222225.6226, { titleCase : true, isAnd : true, noHypen: true }));
// Output: "Four Billion and Twenty Two Million and Two Hundred Twenty Two Thousand and Two Hundred Twenty Five Point Six Two"

API Reference & Options 📚 Options for numberToWords & numberToCurrencyWords

Option	Type	Default	Description	Effect Example
`noComa`	boolean	false	Include or exclude commas between large number groups.	false: "One Million, Two Hundred Thousand" true: "One Million Two Hundred Thousand"
`isAnd`	boolean	false	Insert the word `and` between number groups for formal reading.	false: "One Million Two Hundred Thousand" true: "One Million and Two Hundred Thousand"
`noHypen`	boolean	false	Remove hyphens in compound numbers (e.g. "Twenty-Five" → "Twenty Five").	false: "Twenty-Five" true: "Twenty Five"
`titleCase`	boolean	false	Output words in Title Case, capitalizing hyphenated parts as well.	false: "Twenty-five" true: "Twenty-Five"

Option Effects Examples

// Input number: 125.55

// Default
numberToWords(125.55);
// Output: "One Hundred Twenty Five and Point Five Five"

// noComa: true
numberToWords(125.55, { noComa: true });
// Output: "One Hundred Twenty Five and Point Five Five" (no commas)

// isAnd: true
numberToWords(125.55, { isAnd: true });
// Output: "One Hundred and Twenty Five and Point Five Five"

// noHypen: true
numberToWords(125.55, { noHypen: true });
// Output: "One Hundred Twenty Five and Point Five Five" (no hyphen in "Twenty Five")

// titleCase: true
numberToWords(125.55, { titleCase: true });
// Output: "One Hundred Twenty-Five and Point Five Five" (capitalized words)

🌍 Supported Countries

This package supports 130+ countries using ISO 3166-1 alpha-2 codes.

Country	Code	Country	Code	Country	Code
Afghanistan	AF	Albania	AL	Algeria	DZ
Angola	AO	Argentina	AR	Armenia	AM
Australia	AU	Austria	AT	Azerbaijan	AZ
Bahrain	BH	Bangladesh	BD	Belarus	BY
Belgium	BE	Benin	BJ	Bolivia	BO
Bosnia and Herzegovina	BA	Brazil	BR	Bulgaria	BG
Burkina Faso	BF	Cambodia	KH	Cameroon	CM
Canada	CA	Chile	CL	China	CN
Colombia	CO	Costa Rica	CR	Croatia	HR
Cuba	CU	Czech Republic	CZ	DR Congo	CD
Denmark	DK	Ecuador	EC	Egypt	EG
El Salvador	SV	Estonia	EE	Ethiopia	ET
Finland	FI	France	FR	Gabon	GA
Georgia	GE	Germany	DE	Ghana	GH
Greece	GR	Guatemala	GT	Guinea	GN
Haiti	HT	Honduras	HN	Hong Kong	HK
Hungary	HU	India	IN	Indonesia	ID
Iran	IR	Iraq	IQ	Ireland	IE
Israel	IL	Italy	IT	Ivory Coast	CI
Japan	JP	Jordan	JO	Kazakhstan	KZ
Kenya	KE	Kuwait	KW	Kyrgyzstan	KG
Laos	LA	Latvia	LV	Lebanon	LB
Libya	LY	Lithuania	LT	Madagascar	MG
Malawi	MW	Malaysia	MY	Mali	ML
Mexico	MX	Moldova	MD	Morocco	MA
Mozambique	MZ	Myanmar	MM	Namibia	NA
Nepal	NP	Netherlands	NL	New Zealand	NZ
Nicaragua	NI	Niger	NE	Nigeria	NG
North Macedonia	MK	Norway	NO	Oman	OM
Pakistan	PK	Palestine	PS	Panama	PA
Paraguay	PY	Peru	PE	Philippines	PH
Poland	PL	Portugal	PT	Qatar	QA
Romania	RO	Russia	RU	Rwanda	RW
Saudi Arabia	SA	Senegal	SN	Serbia	RS
Sierra Leone	SL	Singapore	SG	Slovakia	SK
Slovenia	SI	South Africa	ZA	South Korea	KR
South Sudan	SS	Spain	ES	Sri Lanka	LK
Sudan	SD	Sweden	SE	Switzerland	CH
Syria	SY	Tajikistan	TJ	Taiwan	TW
Tanzania	TZ	Thailand	TH	Tunisia	TN
Turkey	TR	Turkmenistan	TM	Uganda	UG
Ukraine	UA	United Arab Emirates	AE	United Kingdom	GB
United States	US	Uruguay	UY	Uzbekistan	UZ
Venezuela	VE	Vietnam	VN	Yemen	YE
Zambia	ZM	Zimbabwe	ZW

TypeScript Support ✅

This package includes full TypeScript type definitions:

import { numberToWords, numberToCurrencyWords, CountryCode } from 'number-to-words';

const amount: string = numberToCurrencyWords(123.45, 'US' as CountryCode);

Benchmarks ⚡

✅ Converts up to quadrillion-range numbers in <1ms
✅ Zero dependencies ensures lightning-fast startup

Browser Compatibility 🌐

This library is fully compatible with:

✅ Node.js (14+)
✅ All modern browsers
✅ Works with bundlers like Webpack, Vite, and Rollup
✅ Works in serverless functions and frontend apps

Contributing 🤝

Contributions are welcome! Please:

Fork the repository
Create a new branch
Submit an issue or feature request
Open a Pull Request

License 📄

See LICENSE for full details.