API Reference

type NumberType = string | number | bigint | null | undefined;

function readVnNumber(number: string | number | bigint): string;

import { readVnNumber } from 'vn-number';// Basic numbersreadVnNumber(0);// → "không"readVnNumber(15);// → "mười lăm"readVnNumber(21);// → "hai mươi mốt"// Hundreds with special rulesreadVnNumber(101);// → "một trăm lẻ một"readVnNumber(205);// → "hai trăm lẻ năm"// ThousandsreadVnNumber(1234);// → "một nghìn hai trăm ba mươi bốn"readVnNumber(10000);// → "mười nghìn"// MillionsreadVnNumber(1250000);// → "một triệu hai trăm năm mươi nghìn"readVnNumber(19990000);// → "mười chín triệu chín trăm chín mươi nghìn"// Billions (tỷ)readVnNumber(1000000000);// → "một tỷ"readVnNumber(2500000000);// → "hai tỷ năm trăm triệu"// Using string for very large numbersreadVnNumber('1000000000000');// → "một nghìn tỷ" (1 trillion)readVnNumber('1000000000000000');// → "một triệu tỷ" (1 quadrillion)// Using bigint for extremely large numbersreadVnNumber(BigInt('1000000000000000000'));// → "một tỷ tỷ" (1 quintillion)readVnNumber(BigInt('9999999999999999'));// → "chín triệu chín trăm chín mươi chín nghìn chín trăm chín mươi chín tỷ chín trăm chín mươi chín triệu chín trăm chín mươi chín nghìn chín trăm chín mươi chín"

function formatVnNumber(  number: NumberType,  fallbackValue: string = '0',): string;

import { formatVnNumber } from 'vn-number';// Basic formattingformatVnNumber(1000);// → "1.000"formatVnNumber(1250000);// → "1.250.000"formatVnNumber(10000000);// → "10.000.000"// Negative numbersformatVnNumber(-5000);// → "-5.000"// Decimal numbersformatVnNumber(1234.56);// → "1.234,56" (note: comma as decimal separator)// Using bigint for very large numbersformatVnNumber(BigInt(10000000));// → "10.000.000"formatVnNumber(BigInt('9999999999999999'));// → "9.999.999.999.999.999"// Handling invalid input with fallbackformatVnNumber('invalid');// → "0" (default fallback)formatVnNumber('invalid', 'N/A');// → "N/A"formatVnNumber(null, 'Không giới hạn');// → "Không giới hạn"formatVnNumber(undefined, '');// → ""formatVnNumber(Number.NaN, 'Lỗi');// → "Lỗi"// String numbers are parsedformatVnNumber('1250000');// → "1.250.000"formatVnNumber('1000.50');// → "1.000,5"

function formatVnCurrency(  money: NumberType,  fallbackValue: string = '0\u00A0₫',): string;

import { formatVnCurrency } from 'vn-number';// Basic currency formattingformatVnCurrency(1250000);// → "1.250.000 ₫"formatVnCurrency(50000);// → "50.000 ₫"formatVnCurrency(0);// → "0 ₫"// Negative amountsformatVnCurrency(-10000);// → "-10.000 ₫"// Large amounts with bigintformatVnCurrency(BigInt(10000000));// → "10.000.000 ₫"formatVnCurrency(BigInt('9999999999999999'));// → "9.999.999.999.999.999 ₫"// Decimal amounts (for partial dong, though rare in practice)formatVnCurrency(1234.56);// → "1.234,56 ₫"// Handling invalid input with fallbackformatVnCurrency(null);// → "0 ₫" (default fallback)formatVnCurrency(null, 'Không giới hạn');// → "Không giới hạn"formatVnCurrency(undefined, '');// → ""formatVnCurrency('invalid', 'Lỗi');// → "Lỗi"formatVnCurrency(Number.NaN, 'Không xác định');// → "Không xác định"// String numbers are parsedformatVnCurrency('1250000');// → "1.250.000 ₫"

function formatVnPercent(  value: NumberType,  fallbackValue: string = '0%',): string;

import { formatVnPercent } from 'vn-number';// Basic percentage formattingformatVnPercent(0.5);// → "50%"formatVnPercent(0.991);// → "99,1%"formatVnPercent(1);// → "100%"formatVnPercent(0.1234);// → "12,34%"// Values over 1 (multiplied by 100)formatVnPercent(1.5);// → "150%"formatVnPercent(2);// → "200%"// Very small percentagesformatVnPercent(0.001);// → "0,1%"formatVnPercent(0.0025);// → "0,25%"// ZeroformatVnPercent(0);// → "0%"// Negative percentagesformatVnPercent(-0.15);// → "-15%"// Using bigint (treated as whole number, multiplied by 100)formatVnPercent(BigInt(1));// → "100%"formatVnPercent(BigInt(5));// → "500%"// Handling invalid input with fallbackformatVnPercent('invalid');// → "0%" (default fallback)formatVnPercent(null, 'N/A');// → "N/A"formatVnPercent(undefined, '');// → ""formatVnPercent('null', 'Không xác định');// → "Không xác định"formatVnPercent(Number.NaN, 'Lỗi');// → "Lỗi"// String numbers are parsedformatVnPercent('0.99');// → "99%"formatVnPercent('0.5');// → "50%"

import { formatVnCurrency, formatVnPercent, readVnNumber } from 'vn-number';interface Product {  name: string;  price: number;  originalPrice?: number;  discount?: number;}function ProductCard({ name, price, originalPrice, discount }: Product) {  const priceText = formatVnCurrency(price);  const priceInWords = readVnNumber(price);  return (    <div className="product-card">      <h3>{name}</h3>      <div className="price">        <span className="current">{priceText}</span>        {originalPrice && (          <span className="original">{formatVnCurrency(originalPrice)}</span>        )}      </div>      {discount && (        <span className="discount-badge">Giảm {formatVnPercent(discount)}</span>      )}      <p className="price-words" aria-label={`Giá ${priceInWords} đồng`}>        {priceInWords} đồng      </p>    </div>  );}// Usage<ProductCard  name="Laptop Dell XPS 13"  price={25000000}  originalPrice={30000000}  discount={0.166}/>;// Displays:// Current price: "25.000.000 ₫"// Original price: "30.000.000 ₫"// Discount: "Giảm 16,6%"// Words: "hai mươi lăm triệu đồng"

import { formatVnNumber, formatVnCurrency, formatVnPercent } from 'vn-number';interface Statistics {  revenue: number;  users: number;  growth: number;  conversion: number;}function Dashboard({ revenue, users, growth, conversion }: Statistics) {  return (    <div className="dashboard">      <div className="stat-card">        <h4>Doanh thu</h4>        <p className="value">{formatVnCurrency(revenue)}</p>        <p className="growth">          {growth >= 0 ? '↑' : '↓'} {formatVnPercent(Math.abs(growth))}        </p>      </div>      <div className="stat-card">        <h4>Người dùng</h4>        <p className="value">{formatVnNumber(users)}</p>      </div>      <div className="stat-card">        <h4>Tỷ lệ chuyển đổi</h4>        <p className="value">{formatVnPercent(conversion)}</p>      </div>    </div>  );}// Usage<Dashboard  revenue={125000000}  users={1234567}  growth={0.157}  conversion={0.0342}/>;

import { readVnNumber, formatVnCurrency } from 'vn-number';function generateCheckText(amount: number, recipient: string): string {  const amountFormatted = formatVnCurrency(amount);  const amountInWords = readVnNumber(amount);  return `Trả cho: ${recipient}Số tiền: ${amountFormatted}Bằng chữ: ${amountInWords.charAt(0).toUpperCase() + amountInWords.slice(1)} đồng chẵn  `.trim();}console.log(generateCheckText(2450000, 'Nguyễn Văn A'));// Output:// Trả cho: Nguyễn Văn A// Số tiền: 2.450.000 ₫// Bằng chữ: Hai triệu bốn trăm năm mươi nghìn đồng chẵn

import { formatVnNumber, formatVnCurrency } from 'vn-number';function PriceInput() {  const [value, setValue] = React.useState('');  const [preview, setPreview] = React.useState('');  const handleChange = (e: React.ChangeEvent<HTMLInputElement>) => {    const rawValue = e.target.value.replace(/\./g, '');    setValue(rawValue);    // Show formatted preview    const numValue = parseFloat(rawValue);    if (!isNaN(numValue)) {      setPreview(formatVnCurrency(numValue));    } else {      setPreview('');    }  };  return (    <div>      <input        type="text"        value={value}        onChange={handleChange}        placeholder="Nhập số tiền"      />      {preview && <p className="preview">{preview}</p>}    </div>  );}

import { formatVnNumber, formatVnCurrency, formatVnPercent } from 'vn-number';// Invalid strings return fallbackformatVnNumber('not a number'); // → "0"formatVnCurrency('invalid', 'Error'); // → "Error"formatVnPercent('xyz'); // → "0%"// Null and undefined return fallbackformatVnNumber(null, '-'); // → "-"formatVnCurrency(undefined); // → "0 ₫"formatVnPercent(null); // → "0%"// NaN returns fallbackformatVnNumber(Number.NaN); // → "0"formatVnCurrency(Number.NaN, 'N/A'); // → "N/A"formatVnPercent(Number.NaN); // → "0%"