to-words

Number to Words

Introduction

Converts Numbers (including decimal points) into words. It also converts the numbers into words for currency.

Installation

npm install to-words --save

Usage

Importing

const { ToWords } = require('to-words');

OR

import { ToWords } from 'to-words';

Config Options

const toWords = new ToWords({
  localeCode: 'en-IN',
  converterOptions: {
    currency: true,
    ignoreDecimal: false,
    ignoreZeroCurrency: false,
    doNotAddOnly: false,
    currencyOptions: {
      // can be used to override defaults for the selected locale
      name: 'Rupee',
      plural: 'Rupees',
      symbol: '₹',
      fractionalUnit: {
        name: 'Paisa',
        plural: 'Paise',
        symbol: '',
      },
    },
  },
});

Options can be set at instance level, or along with individual call to convert method.

const toWords = new ToWords();

let words = toWords.convert(123);
// words = One Hundred Twenty Three

words = toWords.convert(123.45);
// words = One Hundred Twenty Three Point Fourty Five

words = toWords.convert(123.045);
// words = One Hundred Twenty Three Point Zero Four Five

Note: When fractional part starts with zero, the digits after decimal points are converted into respective numbers individually

To convert to currency

const toWords = new ToWords();

let words = toWords.convert(452, { currency: true });
// words = Four Hundred Fifty Two Rupees Only

words = toWords.convert(452.36, { currency: true });
// words = Four Hundred Fifty Two Rupees And Thirty Six Paise Only

To discard fractional unit

const toWords = new ToWords();

let words = toWords.convert(452.36, { currency: true, ignoreDecimal: true });
// words = Four Hundred Fifty Two Rupees Only

To ignore major currency number when it's zero

const toWords = new ToWords();

let words = toWords.convert(0.572, { currency: true, ignoreZeroCurrency: true });
// words = Five Hundred Seventy Two Paise Only

Options

Option	Type	Default	Description
localeCode	string	'en-IN'	Locale code for selecting i18n.
currency	boolean	false	Whether the number to be converted into words written as currency. Note: When currency:true, number will be rounded off to two decimals before converting to words
ignoreDecimal	boolean	false	Whether to ignore fractional unit of number while converting into words.
ignoreZeroCurrency	boolean	false	Whether to ignore zero currency value while converting into words.
doNotAddOnly	boolean	false	Do not add only at the end of the words. This works only when currency = true
currencyOptions	object	undefined	By default currency options are taken from the specified locale. This option allows to specify different currency options while keeping the language details from the selected locale (e.g. convert to English text but use EUR as a currency). You can define different currencies for each call to convert() so it works also if you need to dynamically support multiple currencies. This works only when currency = true

Supported Locale

Country	Language	Locale
UAE	English	en-AE
Bangladesh	English	en-BD
UK	English	en-GB
Ghana	English	en-GH
Ireland	English	en-IE
India	English	en-IN (default)
Myanmar	English	en-MM
Mauritius	English	en-MU
Nigeria	English	en-NG
Nepal	English	en-NP
USA	English	en-US
Philippines	English	en-PH
Estonia	Estonian	ee-EE
Iran	Persian	fa-IR
Belgium	French	fr-BE
France	French	fr-FR
India	Gujarati	gu-IN
India	Hindi	hi-IN
India	Marathi	mr-IN
Suriname	Dutch	nl-SR
Brazil	Portuguese	pt-BR
Turkey	Turkish	tr-TR
Korean, Republic of	Hangul	ko-KR

Inspiration for core logic

https://stackoverflow.com/a/46221860

Changelog

4.1.0 (2024-07-17)

Features

• expose locales in an iterable capacity (cb7b8cf)
• locales: spanish support added (20b7aa6)

Bug Fixes

• add optional trailing variant to exactWordsMapping (44fd000)
• annotate types of test macro entries properly (37c7768)
• use singular field of CurrencyOptions (566ae94)