num2words-uz

A lightweight, dependency-free TypeScript library that converts numbers into words in Uzbek (Latin & Cyrillic), Russian and English — with built-in currency support for som, dollar, ruble and euro.

🔢 ➡️ 🔡

1500.5  ➡  bir ming besh yuz so'm ellik tiyin
25.5    ➡  yigirma besh dollar ellik sent
1234    ➡  bir ming ikki yuz o'ttiz to'rt

Features

• 🇺🇿 Uzbek — both Latin (uz) and Cyrillic (uz-cyrl) scripts
• 🇷🇺 Russian (ru) — correct grammatical gender and plural forms (один рубль, две копейки, пять рублей)
• 🇬🇧 English (en)
• 💵 Currencies — som (UZS), dollar (USD), ruble (RUB), euro (EUR), plus your own
• 🪙 Subunits — tiyin / cent / kopek, derived from the fractional part
• 📦 ESM + CommonJS + type declarations — framework-agnostic: works out of the box in React, Next.js, Vue, Nuxt, Svelte, Angular, Node and the browser
• 🖥️ SSR-safe — no browser APIs, no side effects
• 🌳 Zero dependencies, tree-shakeable
• ✅ Fully covered by unit tests

Installation

npm install num2words-uz
# or
yarn add num2words-uz
# or
pnpm add num2words-uz

Usage

import { numberToWords, somToWords, currencyToWords } from 'num2words-uz';

// Plain numbers
numberToWords(1234);            // "bir ming ikki yuz o'ttiz to'rt"
numberToWords(1234, 'uz-cyrl'); // "бир минг икки юз ўттиз тўрт"
numberToWords(1234, 'ru');      // "одна тысяча двести тридцать четыре"
numberToWords(1234, 'en');      // "one thousand two hundred thirty-four"

// Uzbek som (UZS)
somToWords(1500.5);                    // "bir ming besh yuz so'm ellik tiyin"
somToWords(1500);                      // "bir ming besh yuz so'm"
somToWords(1500, { lang: 'uz-cyrl' }); // "бир минг беш юз сўм"

// Other currencies
currencyToWords(25.5, { currency: 'usd' });               // "yigirma besh dollar ellik sent"
currencyToWords(150, { currency: 'rub' });                // "yuz ellik rubl"
currencyToWords(10.25, { currency: 'eur' });              // "o'n yevro yigirma besh sent"
currencyToWords(1.01, { currency: 'rub', lang: 'ru' });   // "один рубль одна копейка"

With CommonJS:

const { somToWords } = require('num2words-uz');
somToWords(99.99); // "to'qson to'qqiz so'm to'qson to'qqiz tiyin"

Framework usage

The library is plain TypeScript with no dependencies, so it works the same in every framework — and it is safe to call during server-side rendering.

React / Next.js

import { somToWords } from 'num2words-uz';

export function AmountInWords({ amount }: { amount: number }) {
  return <p>{somToWords(amount, { capitalize: true })}</p>;
}

// <AmountInWords amount={1500000} />
// => "Bir million besh yuz ming so'm"

Vue / Nuxt

<script setup lang="ts">
import { computed } from 'vue';
import { somToWords } from 'num2words-uz';

const props = defineProps<{ amount: number }>();
const inWords = computed(() => somToWords(props.amount, { capitalize: true }));
</script>

<template>
  <p>{{ inWords }}</p>
</template>

<!-- <AmountInWords :amount="1500000" /> -->
<!-- => "Bir million besh yuz ming so'm" -->

Nuxt needs no extra configuration — the package ships both ESM and CommonJS builds, so it does not have to be added to build.transpile.

Node / plain JavaScript

const { somToWords } = require('num2words-uz');

console.log(somToWords(1500000, { capitalize: true }));
// "Bir million besh yuz ming so'm"

API

numberToWords(value, lang?)

Converts an integer into words. The fractional part is rounded.

| Parameter | Type | Default | Description | | --- | --- | --- | --- | | value | number \| string | — | The number to convert | | lang | 'uz' \| 'uz-cyrl' \| 'ru' \| 'en' | 'uz' | Output language |

Negative values are prefixed with minus (минус in Russian and Uzbek Cyrillic).

currencyToWords(amount, options?)

Converts a monetary amount into words. The fractional part becomes subunits (tiyin / cent / kopek).

| Option | Type | Default | Description | | --- | --- | --- | --- | | currency | 'uzs' \| 'usd' \| 'rub' \| 'eur' \| CurrencyDef | 'uzs' | Currency code or a custom definition | | lang | Lang | 'uz' | Output language | | showSub | boolean | true | Include the subunit | | alwaysShowSub | boolean | false | Include the subunit even when it is zero | | capitalize | boolean | false | Capitalize the first letter |

somToWords(amount, options?)

Convenience wrapper around currencyToWords with currency: 'uzs'. Options: lang, showTiyin, alwaysShowTiyin, capitalize.

somToWords(1500.5, { showTiyin: false });      // "bir ming besh yuz so'm"
somToWords(1500, { alwaysShowTiyin: true });   // "bir ming besh yuz so'm nol tiyin"
somToWords(1234, { capitalize: true });        // "Bir ming ikki yuz o'ttiz to'rt so'm"

Custom currencies

import { currencyToWords, CurrencyDef } from 'num2words-uz';

const gbp: CurrencyDef = {
  main: { uz: 'funt', 'uz-cyrl': 'фунт', ru: ['фунт', 'фунта', 'фунтов'], ruGender: 0, en: ['pound', 'pounds'] },
  sub:  { uz: 'pens', 'uz-cyrl': 'пенс', ru: ['пенс', 'пенса', 'пенсов'], ruGender: 0, en: ['penny', 'pence'] },
  subInMain: 100,
};

currencyToWords(5.5, { currency: gbp, lang: 'uz' }); // "besh funt ellik pens"

ruGender — 0 for masculine (один), 1 for feminine (одна). Required so Russian numerals agree with the noun.

Limitations

• Supports values up to one quadrillion (within JavaScript's number range).
• In the currency helpers the fractional part is treated as subunits (max 2 decimal places).

License

MIT