Hidden

Overview

Formats an amount as a currency string using locale-specific formatting rules. Supports custom locale specification or uses default system locale.

amount.format(<locale>);

Features

• Returns a formatted currency string with appropriate symbols
• Supports custom locale specification
• Uses system default locale when none provided
• Handles different currency formatting conventions
• Includes proper decimal places and thousands separators
• Simple and intuitive API
• No side effects - read-only operation
• Comprehensive testing

Arguments

Arg	Type	Default Value	Required
locale	string	System default	No

Usage

From an Amount instance, use the format() method to get a formatted currency string.

import { amount } from '@inpulse-ui/utils';

const myAmount = amount(1234.56, 'USD');
const formatted = myAmount.format();

console.log(formatted); // "$1,234.56" (in US locale)

Format with specific locale:

const price = amount(1234.56, 'EUR');

console.log(price.format('en-US')); // "€1,234.56"
console.log(price.format('de-DE')); // "1.234,56 €"
console.log(price.format('fr-FR')); // "1 234,56 €"

Different currencies with locales:

const usdAmount = amount(9999.99, 'USD');
const eurAmount = amount(8500.50, 'EUR');
const gbpAmount = amount(7525.25, 'GBP');

// US locale formatting
console.log(usdAmount.format('en-US')); // "$9,999.99"
console.log(eurAmount.format('en-US')); // "€8,500.50"
console.log(gbpAmount.format('en-US')); // "£7,525.25"

// German locale formatting
console.log(usdAmount.format('de-DE')); // "9.999,99 $"
console.log(eurAmount.format('de-DE')); // "8.500,50 €"
console.log(gbpAmount.format('de-DE')); // "7.525,25 £"

Handles negative values:

const negativeAmount = amount(-250.75, 'USD');

console.log(negativeAmount.format('en-US')); // "-$250.75"
console.log(negativeAmount.format('de-DE')); // "-250,75 $"

Zero and small values:

const zeroAmount = amount(0, 'USD');
const smallAmount = amount(0.01, 'USD');

console.log(zeroAmount.format()); // "$0.00"
console.log(smallAmount.format()); // "$0.01"

Display in user interfaces:

const orderItems = [
  { name: 'Product A', price: amount(29.99, 'USD') },
  { name: 'Product B', price: amount(45.50, 'USD') },
  { name: 'Shipping', price: amount(9.95, 'USD') }
];

// Format for display
orderItems.forEach(item => {
  console.log(`${item.name}: ${item.price.format()}`);
});
// Product A: $29.99
// Product B: $45.50
// Shipping: $9.95

Internationalization in applications:

const productPrice = amount(199.99, 'USD');
const userLocale = navigator.language || 'en-US';

// Format according to user's locale
const displayPrice = productPrice.format(userLocale);

// Update UI
document.getElementById('price-display').textContent = displayPrice;

// For different regions
const localizedPrices = {
  us: productPrice.format('en-US'),    // "$199.99"
  uk: productPrice.format('en-GB'),    // "US$199.99"
  germany: productPrice.format('de-DE'), // "199,99 $"
  france: productPrice.format('fr-FR')   // "199,99 $US"
};

console.log(localizedPrices);