Getting Started - Khanh Docs

Zero Dependencies

vn-number has zero runtime dependencies, making it lightweight and perfect for performance-critical applications. It uses the standard Intl.NumberFormat API for formatting, ensuring consistent behavior across all JavaScript environments without external dependencies.

Battle-Tested in Production

This library is battle-tested in production apps and dashboards, providing reliable number formatting and reading for any applications that need to process Vietnamese numeric data.

Installation#

bun add vn-number

pnpm add vn-number

yarn add vn-number

npm install vn-number

deno add jsr:@hckhanh/vn-number

Note

TypeScript Support

vn-number is written in TypeScript and includes type definitions out of the box. No need to install separate @types packages!

Basic Usage#

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(1001);// Output: "một nghìn không trăm lẻ 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%"

Usage Examples#

Working with Large Numbers#

The library handles very large numbers using string or bigint:

import { readVnNumber } from 'vn-number';// Using string for very large numbersreadVnNumber('1000000000000');// Output: "một nghìn tỷ"// Using bigintreadVnNumber(BigInt('1000000000000000000'));// Output: "một tỷ tỷ"

Handling Invalid Input#

All formatting functions support fallback values:

import { formatVnNumber, formatVnCurrency } from 'vn-number';formatVnNumber('invalid', 'N/A');// Output: "N/A"formatVnNumber(null);// Output: "0" (default fallback)formatVnCurrency(undefined, '');// Output: ""

Vietnamese Number Reading Rules#

The readVnNumber function follows Vietnamese language rules:

import { readVnNumber } from 'vn-number';// Special rule: "lăm" instead of "năm" in tens positionreadVnNumber(15); // "mười lăm"readVnNumber(25); // "hai mươi lăm"// Special rule: "mốt" instead of "một" after tensreadVnNumber(21); // "hai mươi mốt"readVnNumber(31); // "ba mươi mốt"// Special rule: "lẻ" for single digits after hundredsreadVnNumber(101); // "một trăm lẻ một"readVnNumber(305); // "ba trăm lẻ năm"

Common Use Cases#

E-commerce Applications#

import { formatVnCurrency, readVnNumber } from 'vn-number';const price = 1500000;// Display formatted priceconsole.log(formatVnCurrency(price));// Output: "1.500.000 ₫"// Read price aloud (for accessibility)console.log(readVnNumber(price));// Output: "một triệu năm trăm nghìn"

Banking and Financial Applications#

import { readVnNumber, formatVnCurrency } from 'vn-number';const amount = 2450000;// Show formatted amountconsole.log(`Số tiền: ${formatVnCurrency(amount)}`);// Output: "Số tiền: 2.450.000 ₫"// Generate check textconsole.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%"