IndicNumberWords 🇮🇳

Zero-dependency, high-performance TypeScript/JavaScript library to format numbers into the Indian Numbering System (Lakhs, Crores, Arabs), convert numbers to words, currency phrases, traditional Indian fractional terms, native script numerals, and ordinals across 18 Indic languages (including Sanskrit).

🚀 Quick Install

npm i indic-number-words

📑 Table of Contents

• Features
• Supported Languages (18)
• Installation
• Quick Start
• Complete Test & Demo Script
• Full API Reference
  • toWords(val, options)
  • toCurrency(val, options)
  • formatIndic(val)
  • toCompact(val, options)
  • toNativeDigits(val, options)
  • toFraction(val, options)
  • toOrdinal(val, options)
  • registerLanguage(dictionary)
  • getLanguageDictionary(code)
• Options Object Schema
• Framework Integration Examples
• License

✨ Features

• 🚀 Zero Dependencies: Lightweight, ultra-fast tree-shakeable ES/CommonJS modules.
• 🇮🇳 18 Indic Languages: Includes Sanskrit, Marathi, Hindi, Gujarati, Bengali, Tamil, Telugu, Kannada, Malayalam, Odia, Punjabi, Assamese, Urdu, Konkani, Maithili, Sindhi, Nepali, and Indian English.
• 🔢 Indian Comma Placement: Group numbers naturally into Thousands, Lakhs, Crores, and Arabs (1,23,45,678.50).
• 💵 Currency Phrase Formatting: Auto-convert decimals into Rupees & Paise phrasing ("Rupees One Lakh Twenty Five Thousand and Fifty Paise Only").
• 🥧 Traditional Fractional Phrases: Full support for 0.25 (Quarter / पाव / पाद्), 0.5 (Half / अर्धा / आधा / अर्धम्), 1.5 (Deadh / दीड / डेढ़ / सार्धम्), 2.5 (Dhai / अडीच / ढाई / अध्यर्धम्).
• ✍️ Native Script Converter: Convert Western ASCII numbers (12345) into native Indic script numerals (१२३४५, ૧૨૩૪૫, ௧௨௩௪௫).
• 🥇 Ordinals Support: Generate ordinals (1st, 2nd, 3rd / प्रथमः, द्वितीयः / पहिला, दुसरा / पहला, दूसरा).

🌟 Supported Languages (18)

| Language | Code | Native Name | Native Digits (123) | Sample Fraction (1.5) | Sample Ordinal (1st) | | :--- | :--- | :--- | :--- | :--- | :--- | | Sanskrit | sa | संस्कृतम् | १२३ | सार्धम् | प्रथमः | | Marathi | mr | मराठी | १२३ | दीड | पहिला | | Hindi | hi | हिंदी | १२३ | डेढ़ | पहला | | English | en | English | 123 | One and a Half | First | | Gujarati | gu | ગુજરાતી | ૧૨૩ | દોઢ | પહેલો | | Bengali | bn | বাংলা | ১২৩ | দেড় | প্রথম | | Tamil | ta | தமிழ் | ௧௨௩ | ஒன்றரை | முதல் | | Telugu | te | తెలుగు | ౧౨౩ | ఒకటిన్నర | మొదటి | | Kannada | kn | ಕನ್ನಡ | ೧೨೩ | ಒಂದೂವರೆ | ಮೊದಲ | | Malayalam| ml | മലയാളം | ൧൨൩ | ഒന്നര | ഒന്നാം | | Odia | or | ଓଡ଼ିଆ | ୧୨୩ | ଡେଢ଼ | ପ୍ରଥମ | | Punjabi | pa | ਪੰਜਾਬੀ | ੧੨੩ | ਡੇਢ | ਪਹਿਲਾ | | Assamese | as | অসমীয়া | ১২৩ | দেৰ | প্ৰথম | | Urdu | ur | اردو | ۱۲۳ | ڈیڑھ | پہلا | | Konkani | kok | कोंकणी | १२३ | दीड | पयलो | | Maithili | mai | मैथिली | १२३ | डेढ़ | पहिल | | Sindhi | sd | सिंधी | १२३ | डेढ़ | पहिरों | | Nepali | ne | नेपाली | १२३ | डेढ | पहिलो |

📦 Installation

npm i indic-number-words

💻 Quick Start

import { 
  formatIndic, 
  toWords, 
  toCurrency, 
  toCompact, 
  toNativeDigits, 
  toFraction, 
  toOrdinal 
} from 'indic-number-words';

// 1. Indian Digit Formatting
console.log(formatIndic(12345678.50)); 
// ➔ "1,23,45,678.50"

// 2. Number to Words in Sanskrit
console.log(toWords(125050, 'sa')); 
// ➔ "एकम् लक्षम् पञ्चविंशतिः सहस्रम् पञ्चाशत्"

// 3. Number to Words in Marathi
console.log(toWords(125050, 'mr')); 
// ➔ "एक लाख पंचवीस हजार पन्नास"

// 4. Native Numeral Converter in Tamil
console.log(toNativeDigits(12345, 'ta')); 
// ➔ "௧௨௩௪௫"

// 5. Indian Fractional Term in Hindi
console.log(toFraction(1.5, 'hi')); 
// ➔ "डेढ़"

// 6. Ordinal Number in Sanskrit
console.log(toOrdinal(1, 'sa')); 
// ➔ "प्रथमः"

🧪 Complete Test & Demo Script

Create test.js after running npm i indic-number-words:

const { 
  formatIndic, 
  toWords, 
  toCurrency, 
  toCompact, 
  toNativeDigits, 
  toFraction, 
  toOrdinal 
} = require('indic-number-words');

const languages = [
  'sa', 'mr', 'hi', 'en', 'gu', 'bn', 'ta', 'te', 
  'kn', 'ml', 'or', 'pa', 'as', 'ur', 'kok', 'mai', 'sd', 'ne'
];

console.log('==================================================');
console.log(' 🇮🇳 IndicNumberWords - All 7 Methods x 18 Languages');
console.log('==================================================\n');

// Method 1: formatIndic
console.log('📍 1. Indian Digit Grouping (formatIndic):');
console.log('   Result:', formatIndic(12345678.50));

// Method 2: toWords
console.log('\n🗣️ 2. Number to Words (125050):');
languages.forEach(lang => {
  console.log(`   [${lang.padEnd(3)}] :`, toWords(125050, lang));
});

// Method 3: toCurrency
console.log('\n💵 3. Currency Phrasing (125000.50):');
languages.forEach(lang => {
  console.log(`   [${lang.padEnd(3)}] :`, toCurrency(125000.50, lang));
});

// Method 4: toCompact
console.log('\n📊 4. Compact Notation (125000):');
languages.forEach(lang => {
  console.log(`   [${lang.padEnd(3)}] :`, toCompact(125000, lang));
});

// Method 5: toNativeDigits
console.log('\n✍️ 5. Native Script Digits (12345):');
languages.forEach(lang => {
  console.log(`   [${lang.padEnd(3)}] :`, toNativeDigits(12345, lang));
});

// Method 6: toFraction
console.log('\n🥧 6. Indian Fractional Term (1.5):');
languages.forEach(lang => {
  console.log(`   [${lang.padEnd(3)}] :`, toFraction(1.5, lang));
});

// Method 7: toOrdinal
console.log('\n🥇 7. Ordinal Numbers (1st):');
languages.forEach(lang => {
  console.log(`   [${lang.padEnd(3)}] :`, toOrdinal(1, lang));
});

console.log('\n==================================================');

📖 Full API Reference

1. toWords(val, options)

Converts a number or numeric string into words.

• Signature: toWords(val: number | string, options?: SupportedLanguage | Options): string
• Examples:

  toWords(100000, 'en'); // ➔ "One Lakh"
  toWords(100000, 'mr'); // ➔ "एक लाख"
  toWords(100000, 'sa'); // ➔ "एकम् लक्षम्"

2. toCurrency(val, options)

Converts numbers into legal financial/currency phrasing with subunits (Rupees & Paise).

• Signature: toCurrency(val: number | string, options?: SupportedLanguage | Options): string
• Examples:

  toCurrency(125000.50, 'en'); 
  // ➔ "Rupees One Lakh Twenty Five Thousand and Fifty Paise Only"
  
  toCurrency(125000.50, 'mr'); 
  // ➔ "एक लाख पंचवीस हजार रुपये आणि पन्नास पैसे मात्र"

3. formatIndic(val)

Formats numbers according to the Indian digit grouping system.

• Signature: formatIndic(val: number | string): string
• Examples:

  formatIndic(12345678.50); // ➔ "1,23,45,678.50"
  formatIndic(100000);      // ➔ "1,00,000"

4. toCompact(val, options)

Shortens large numbers into Lakh / Crore / Arab notation.

• Signature: toCompact(val: number | string, options?: SupportedLanguage | Options): string
• Examples:

  toCompact(125000, 'en'); // ➔ "1.25 Lakh"
  toCompact(25000000, 'en'); // ➔ "2.5 Crore"
  toCompact(125000, { lang: 'mr', useNativeDigits: true }); // ➔ "१.२५ लाख"

5. toNativeDigits(val, options)

Converts ASCII digits 0-9 into native script numerals.

• Signature: toNativeDigits(val: number | string, options?: SupportedLanguage | Options): string
• Examples:

  toNativeDigits(12345, 'sa'); // ➔ "१२३४५"
  toNativeDigits(12345, 'gu'); // ➔ "૧૨૩૪૫"
  toNativeDigits(12345, 'bn'); // ➔ "১২৩৪৫"
  toNativeDigits(12345, 'ta'); // ➔ "௧௨௩௪௫"

6. toFraction(val, options)

Converts decimal numbers into traditional Indian fractional terms (0.25, 0.5, 0.75, 1.25, 1.5, 2.5, 3.5).

• Signature: toFraction(val: number | string, options?: SupportedLanguage | Options): string
• Examples:

  toFraction(0.5, 'mr'); // ➔ "अर्धा"
  toFraction(1.5, 'hi'); // ➔ "डेढ़"
  toFraction(2.5, 'mr'); // ➔ "अडीच"
  toFraction(1.5, 'sa'); // ➔ "सार्धम्"

7. toOrdinal(val, options)

Converts cardinal numbers into ordinal phrases.

• Signature: toOrdinal(val: number | string, options?: SupportedLanguage | Options): string
• Examples:

  toOrdinal(1, 'sa'); // ➔ "प्रथमः"
  toOrdinal(2, 'sa'); // ➔ "द्वितीयः"
  toOrdinal(1, 'mr'); // ➔ "पहिला"
  toOrdinal(1, 'hi'); // ➔ "पहला"
  toOrdinal(1, 'en'); // ➔ "First"

8. registerLanguage(dictionary)

Dynamically registers a custom language or regional dialect dictionary at runtime.

9. getLanguageDictionary(code)

Gets the language dictionary metadata object for a specific language code.

⚙️ Options Object Schema

interface Options {
  lang?: SupportedLanguage;    // Language code (default: 'en')
  currency?: boolean;          // Format as currency phrase
  compact?: boolean;           // Format as short notation
  useNativeDigits?: boolean;   // Use native Indic digits for numbers
}

📜 License

MIT License © 2026 IndicNumberWords. Free to use for personal, open source, and commercial projects.