🇻🇳 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://vn-number.khanh.id

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.