Skip to main content

​
Number to Words Conversion

The numberToWords utility converts numeric values into their Persian word equivalents with comprehensive support for ordinals, currency formatting, and various number scales.

​
Basic Usage

import { numberToWords } from '@persian-tools/persian-tools';

​
Simple Conversion

numberToWords(1234);
// Output: "یک هزار و دویست و سی و چهار"

numberToWords(0);
// Output: "صفر"

numberToWords(1000000);
// Output: "یک میلیون"

​
Advanced Options

The function accepts an optional configuration object for customized behavior: 
interface NumberToWordsOptions {
	ordinal?: boolean;
	currency?: boolean;
	scale?: "short" | "long";
}

​
Ordinal Numbers

Generate ordinal numbers (first, second, third, etc.) in Persian: 
numberToWords(1, { ordinal: true });
// Output: "یکم"

numberToWords(21, { ordinal: true });
// Output: "بیست و یکم"

numberToWords(100, { ordinal: true });
// Output: "یکصدم"

​
Currency Formatting

Format numbers as currency amounts: 
numberToWords(1500, { currency: true });
// Output: "یک هزار و پانصد تومان"

numberToWords(25000, { currency: true });
// Output: "بیست و پنج هزار تومان"

​
Number Scales

Choose between short and long scale representations: 
numberToWords(1000000000, { scale: 'short' });
// Output: "یک میلیارد"

​
Supported Number Ranges

Range Support

  • Minimum: 0 - Maximum: 999,999,999,999,999 (15 digits) - Decimals: Not supported (integers only) - Negative: Not supported (returns empty string)

​
Examples by Scale

​
Thousands

numberToWords(1000); // "یک هزار"
numberToWords(15000); // "پانزده هزار"
numberToWords(100000); // "یکصد هزار"
numberToWords(999000); // "نهصد و نود و نه هزار"

​
Millions

numberToWords(1000000); // "یک میلیون"
numberToWords(2500000); // "دو میلیون و پانصد هزار"
numberToWords(50000000); // "پنجاه میلیون"

​
Billions and Beyond

numberToWords(1000000000); // "یک میلیارد"
numberToWords(1000000000000); // "یک تریلیون"
numberToWords(1000000000000000); // "یک کوادریلیون"

​
Edge Cases

​
Zero and Invalid Input

numberToWords(0); // "صفر"
numberToWords(null); // ""
numberToWords(undefined); // ""
numberToWords(-100); // "" (negative numbers not supported)
numberToWords(1.5); // "" (decimals not supported)

​
Very Large Numbers

// Maximum supported number
numberToWords(999999999999999);
// "نهصد و نود و نه کوادریلیون و نهصد و نود و نه تریلیون و نهصد و نود و نه میلیارد و نهصد و نود و نه میلیون و نهصد و نود و نه هزار و نهصد و نود و نه"

// Beyond maximum (returns empty string)
numberToWords(1000000000000000); // ""

​
TypeScript Support

The utility provides full TypeScript support with proper type definitions: 
import { numberToWords, NumberToWordsOptions } from "persian-tools";

const options: NumberToWordsOptions = {
	ordinal: true,
	currency: false,
	scale: "short",
};

const result: string = numberToWords(1234, options);

​
Performance Considerations

  • Cache results for frequently used numbers
  • Use tree-shaking to include only this utility
  • Consider batch processing for large datasets
  • Small numbers (1-999): ~0.1ms
  • Medium numbers (1K-999K): ~0.2ms
  • Large numbers (1M+): ~0.5ms

​
Common Use Cases

​
Invoice Generation

function generateInvoice(amount: number) {
	return {
		numericAmount: addCommas(amount),
		writtenAmount: numberToWords(amount, { currency: true }),
		persianDigits: digitsEnToFa(addCommas(amount)),
	};
}

​
Educational Applications

function createNumberQuiz(number: number) {
	return {
		question: `عدد ${digitsEnToFa(number.toString())} را به حروف بنویسید:`,
		answer: numberToWords(number),
		ordinalAnswer: numberToWords(number, { ordinal: true }),
	};
}

​
Error Handling

The utility handles invalid input gracefully: 
// Always returns a string (empty for invalid input)
const result = numberToWords(invalidInput);
if (result === "") {
	console.log("Invalid input provided");
}

Words to Number

Convert Persian words back to numbers

Add Commas

Format numbers with thousands separators

Digit Conversion

Convert between Persian, Arabic, and English digits

Ordinal Suffix

Add or remove ordinal suffixes