🇻🇳 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

Release Notes

See Releases for changelog and release notes.