vn-number

https://vn-number.khanh.id/docs
Admin
A zero-dependency JavaScript library for formatting and reading Vietnamese numbers, currency, and...
Tokens:4,929
Snippets:32
Trust Score:4.1
Update:10 months ago
Show doc for...
Tokens:
Raw
### Install vn-number using various package managers

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

Install the vn-number library using your preferred package manager. The library has zero runtime dependencies and is written in TypeScript.

```bash
bun add vn-number
```

```bash
pnpm add vn-number
```

```bash
yarn add vn-number
```

```bash
npm install vn-number
```

```bash
deno add jsr:@hckhanh/vn-number
```

--------------------------------

### E-commerce: Displaying Prices and Descriptions with vn-number

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

Illustrates using vn-number in an e-commerce context. 'formatVnCurrency' is used to display prices in VND, while 'readVnNumber' can be used for accessibility features like reading prices aloud.

```javascript
import { formatVnCurrency, readVnNumber } from 'vn-number';

const price = 1500000;

// Display formatted price
console.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"
```

--------------------------------

### Data Visualization: Formatting Numbers and Percentages with vn-number

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

Demonstrates using vn-number for data visualization labels. 'formatVnNumber' formats large numbers for clarity, and 'formatVnPercent' formats growth rates or other percentages according to Vietnamese conventions.

```javascript
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%"
```

--------------------------------

### Import vn-number functions in JavaScript/TypeScript

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

Demonstrates how to import the 'readVnNumber' function from the vn-number library. This function is used to convert numbers into Vietnamese text representations.

```javascript
import { readVnNumber } from 'vn-number';

const result = readVnNumber();
// result: (Enter a number below 👇 to see the result)
```

--------------------------------

### Banking: Formatting Amounts and Check Text with vn-number

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

Shows how vn-number can be applied in banking applications. 'formatVnCurrency' is used for displaying transaction amounts, and 'readVnNumber' generates the text representation for checks.

```javascript
import { readVnNumber, formatVnCurrency } from 'vn-number';

const amount = 2450000;

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

// Generate check text
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"
```

--------------------------------

### Format Percentages in Vietnamese Style using vn-number

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

Formats decimal numbers into percentages using Vietnamese formatting conventions, typically using a comma as the decimal separator and a '%' symbol. This is useful for displaying growth rates or proportions.

```javascript
import { formatVnPercent } from 'vn-number';

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

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

--------------------------------

### Complete E-commerce Product Card Example

Source: https://vn-number.khanh.id/docs/api-reference

This example demonstrates a React component for an e-commerce product card, utilizing `formatVnCurrency`, `formatVnPercent`, and `readVnNumber` from the 'vn-number' library. It showcases how to display product price, original price, discount percentage, and price in words.

```javascript
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"

```

--------------------------------

### Handle Invalid Input and Fallbacks with vn-number

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

Demonstrates how vn-number formatting functions gracefully handle invalid or null/undefined inputs by utilizing provided fallback values. If no fallback is specified, default behaviors (e.g., '0' for formatVnNumber) are applied.

```javascript
import { formatVnNumber, formatVnCurrency } from 'vn-number';

formatVnNumber('invalid', 'N/A');
// Output: "N/A"

formatVnNumber(null);
// Output: "0" (default fallback)

formatVnCurrency(undefined, '');
// Output: ""
```

--------------------------------

### Format Vietnamese Currency (VND) with vn-number

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

Formats numerical values as Vietnamese Dong (VND) currency strings, appending the '₫' symbol. It also supports a fallback string for null or undefined inputs, providing flexibility in display.

```javascript
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"
```

--------------------------------

### Read Vietnamese Numbers with vn-number

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

Converts numerical input into its Vietnamese text equivalent. It handles standard number-to-text conversion and follows specific Vietnamese reading rules like 'lăm', 'mốt', and 'lẻ'. Supports large numbers via string or BigInt.

```javascript
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"

// Using string for very large numbers
readVnNumber('1000000000000');
// Output: "một nghìn tỷ"

// Using bigint
readVnNumber(BigInt('1000000000000000000'));
// Output: "một tỷ tỷ"
```

--------------------------------

### Format Numbers in Vietnamese Style using vn-number

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

Formats numbers using Vietnamese thousand separators (dots). This function is useful for displaying large numbers in a culturally appropriate format. It supports both standard numbers and BigInt for very large values.

```javascript
import { formatVnNumber } from 'vn-number';

formatVnNumber(1250000);
// Output: "1.250.000"

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

--------------------------------

### Format as Vietnamese Percentage

Source: https://vn-number.khanh.id/docs/api-reference

The `formatVnPercent` function formats a number as a Vietnamese percentage. It multiplies the input value by 100 and appends the '%' symbol. It also handles invalid inputs by returning a specified fallback value.

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

```

```javascript
import { formatVnPercent } from 'vn-number';

// Basic percentage formatting
formatVnPercent(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 percentages
formatVnPercent(0.001);
// → "0,1%"

formatVnPercent(0.0025);
// → "0,25%"

// Zero
formatVnPercent(0);
// → "0%"

// Negative percentages
formatVnPercent(-0.15);
// → "-15%"

// Using bigint (treated as whole number, multiplied by 100)
formatVnPercent(BigInt(1));
// → "100%"

formatVnPercent(BigInt(5));
// → "500%"

// Handling invalid input with fallback
formatVnPercent('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 parsed
formatVnPercent('0.99');
// → "99%"

formatVnPercent('0.5');
// → "50%"

```

--------------------------------

### Type Definition: NumberType

Source: https://vn-number.khanh.id/docs/api-reference

Defines the acceptable input types for vn-number formatting functions, including string, number, bigint, null, and undefined. This allows for flexible handling of various data sources.

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

--------------------------------

### Format Vietnamese Number: formatVnNumber()

Source: https://vn-number.khanh.id/docs/api-reference

Formats a number into the standard Vietnamese number format, using dots as thousand separators and a comma as the decimal separator. It accepts various input types and provides a fallback value for invalid inputs.

```typescript
import { formatVnNumber } from 'vn-number';

// Basic formatting
formatVnNumber(1000);
// → "1.000"

formatVnNumber(1250000);
// → "1.250.000"

formatVnNumber(10000000);
// → "10.000.000"

// Negative numbers
formatVnNumber(-5000);
// → "-5.000"

// Decimal numbers
formatVnNumber(1234.56);
// → "1.234,56" (note: comma as decimal separator)

// Using bigint for very large numbers
formatVnNumber(BigInt(10000000));
// → "10.000.000"

formatVnNumber(BigInt('9999999999999999'));
// → "9.999.999.999.999.999"

// Handling invalid input with fallback
formatVnNumber('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 parsed
formatVnNumber('1250000');
// → "1.250.000"

formatVnNumber('1000.50');
// → "1.000,5"

```

--------------------------------

### Format as Vietnamese Dong (VND) Currency

Source: https://vn-number.khanh.id/docs/api-reference

The `formatVnCurrency` function formats a given monetary value into Vietnamese Dong (VND) currency format. It accepts various number types and handles invalid inputs by returning a fallback value. The output includes the VND symbol '₫' and uses appropriate separators.

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

```

```javascript
import { formatVnCurrency } from 'vn-number';

// Basic currency formatting
formatVnCurrency(1250000);
// → "1.250.000 ₫"

formatVnCurrency(50000);
// → "50.000 ₫"

formatVnCurrency(0);
// → "0 ₫"

// Negative amounts
formatVnCurrency(-10000);
// → "-10.000 ₫"

// Large amounts with bigint
formatVnCurrency(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 fallback
formatVnCurrency(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 parsed
formatVnCurrency('1250000');
// → "1.250.000 ₫"

```

--------------------------------

### Read Vietnamese Number: readVnNumber()

Source: https://vn-number.khanh.id/docs/api-reference

Converts a number (string, number, or bigint) into its Vietnamese text representation. It adheres to specific Vietnamese linguistic rules such as 'lăm', 'mốt', and 'lẻ' for accurate pronunciation and includes handling for zero and large numbers.

```typescript
import { readVnNumber } from 'vn-number';

// Basic numbers
readVnNumber(0);
// → "không"

readVnNumber(15);
// → "mười lăm"

readVnNumber(21);
// → "hai mươi mốt"

// Hundreds with special rules
readVnNumber(101);
// → "một trăm lẻ một"

readVnNumber(205);
// → "hai trăm lẻ năm"

// Thousands
readVnNumber(1234);
// → "một nghìn hai trăm ba mươi bốn"

readVnNumber(10000);
// → "mười nghìn"

// Millions
readVnNumber(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 numbers
readVnNumber('1000000000000');
// → "một nghìn tỷ" (1 trillion)

readVnNumber('1000000000000000');
// → "một triệu tỷ" (1 quadrillion)

// Using bigint for extremely large numbers
readVnNumber(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"

```
Tokens:
Raw