🇻🇳 vn-number

🛠 A bunch of utility functions that work with number in 🇻🇳 Vietnamese language

Features

• Zero dependencies
• Built-in support for Edge runtime
• Typesafe with TypeScript
• Fully documented
• Works with number, string, and bigint types
• Handles very large numbers (up to quintillions)
• Battle-tested in production apps and dashboards

Installation

pnpm add vn-number

deno add jsr:@hckhanh/vn-number

Quick Start

Read Vietnamese Numbers

Convert numbers to Vietnamese text:

import { readVnNumber } from 'vn-number'

readVnNumber(1250000)
// Output: "một triệu hai trăm năm mươi nghìn"

readVnNumber(15)
// Output: "mười lăm"

readVnNumber(21)
// Output: "hai mươi mốt"

Format Numbers in Vietnamese Style

Format numbers with Vietnamese thousand separators (dots):

import { formatVnNumber } from 'vn-number'

formatVnNumber(1250000)
// Output: "1.250.000"

formatVnNumber(BigInt('9999999999999999'))
// Output: "9.999.999.999.999.999"

Format Vietnamese Currency (VND)

Format numbers as Vietnamese Dong currency:

import { formatVnCurrency } from 'vn-number'

formatVnCurrency(1250000)
// Output: "1.250.000 ₫"

formatVnCurrency(null, 'Không giới hạn')
// Output: "Không giới hạn"

Format Percentages

Format numbers as Vietnamese-style percentages:

import { formatVnPercent } from 'vn-number'

formatVnPercent(0.991)
// Output: "99,1%"

formatVnPercent(0.5)
// Output: "50%"

Documentation

For detailed documentation, examples, and API reference, visit:

https://docs.khanh.id/vn-number

Common Use Cases

E-commerce

import { formatVnCurrency, readVnNumber } from 'vn-number'

const price = 1500000

console.log(formatVnCurrency(price))
// Output: "1.500.000 ₫"

console.log(readVnNumber(price))
// Output: "một triệu năm trăm nghìn"

Banking and Financial Documents

import { readVnNumber, formatVnCurrency } from 'vn-number'

const amount = 2450000

console.log(`Số tiền: ${formatVnCurrency(amount)}`)
// Output: "Số tiền: 2.450.000 ₫"

console.log(`Bằng chữ: ${readVnNumber(amount)} đồng`)
// Output: "Bằng chữ: hai triệu bốn trăm năm mươi nghìn đồng"

Data Visualization

import { formatVnNumber, formatVnPercent } from 'vn-number'

const totalUsers = 1234567
const growthRate = 0.157

console.log(`Tổng người dùng: ${formatVnNumber(totalUsers)}`)
// Output: "Tổng người dùng: 1.234.567"

console.log(`Tăng trưởng: ${formatVnPercent(growthRate)}`)
// Output: "Tăng trưởng: 15,7%"

Vietnamese Language Rules

The readVnNumber function follows Vietnamese language conventions:

• "lăm" rule: 15 → "mười lăm", 25 → "hai mươi lăm"
• "mốt" rule: 21 → "hai mươi mốt", 31 → "ba mươi mốt"
• "lẻ" rule: 101 → "một trăm lẻ một", 305 → "ba trăm lẻ năm"
• Zero handling: 1001 → "một nghìn không trăm lẻ một"

API Functions

| Function | Description | Example | |----------|-------------|---------| | readVnNumber(number) | Convert number to Vietnamese text | readVnNumber(1250000) → "một triệu hai trăm năm mươi nghìn" | | formatVnNumber(number, fallback?) | Format number in Vietnamese style | formatVnNumber(1250000) → "1.250.000" | | formatVnCurrency(money, fallback?) | Format as VND currency | formatVnCurrency(1250000) → "1.250.000 ₫" | | formatVnPercent(value, fallback?) | Format as percentage | formatVnPercent(0.991) → "99,1%" |

Browser and Runtime Compatibility

• ✅ Node.js 14+
• ✅ Bun
• ✅ Deno
• ✅ Modern browsers (Chrome, Firefox, Safari, Edge)
• ✅ React Native
• ✅ Electron
• ✅ Edge Runtime (Vercel, Cloudflare Workers, etc.)

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

MIT © Khánh Hoàng

Release Notes

See Releases for changelog and release notes.

v3 performance release

The next major release preserves the public API while speeding up number reading. See the benchmark report for reproducible measurements and upgrade notes for compatibility details.