---
name: Number Formatting
description: Best practices for humanely displaying numbers, quantities, currencies, and KPIs in a user-friendly way
---

# Number Formatting Guidelines

When displaying numbers, quantities, currencies, and key performance indicators (KPIs) in your application, follow these rules to ensure numbers are presented in a clear, readable, and humane way:

## General Number Display

1. **Truncate to One Decimal Place**: Always truncate numbers to one decimal place when possible. This makes numbers easier to scan and understand at a glance. For example:
   - `3.7` instead of `3.7234`
   - `12.5` instead of `12.456`
   - `0.8` instead of `0.789`

2. **Whole Numbers**: If a number is a whole number (no meaningful decimal component), display it without decimal places:
   - `5` instead of `5.0`
   - `100` instead of `100.0`

## Quantity Display

3. **Always Use Plural Form**: When displaying quantities with units, always use the plural form of the unit. Never parenthesize the plural form:
   - ✅ **Correct**: "3 things", "1 things", "5 users", "0 items"
   - ❌ **Incorrect**: "3 thing(s)", "1 thing(s)", "5 user(s)"

## Currency Formatting

4. **Use Built-in Currency Formatting**: Always use the browser's built-in currency formatting (e.g., `Intl.NumberFormat` with currency style) rather than manually formatting currency values. This ensures:
   - Proper currency symbols ($, €, £, etc.)
   - Correct decimal places for the currency
   - Appropriate thousands separators
   - Locale-appropriate formatting

5. **Currency Examples**:
   - `$1,234.56` (USD)
   - `€1.234,56` (EUR in some locales)
   - `£1,234.56` (GBP)

6. **Currency Precision**: Follow standard currency conventions:
   - Most currencies use 2 decimal places
   - Some currencies (like Japanese Yen) use 0 decimal places
   - Let the built-in formatter handle this automatically based on locale

## High-Level KPIs and Large Numbers

7. **Round to Nearest Thousand or Million**: For high-level KPIs and large numbers that don't require exact precision, round to the nearest thousand or million and use abbreviated suffixes:
   - Use `k` for thousands (1,000)
   - Use `m` for millions (1,000,000)
   - Use `b` for billions (1,000,000,000) when appropriate

8. **KPI Formatting Examples**:
   - `1.2k` instead of `1,234` (for approximate values)
   - `5.7m` instead of `5,678,901` (for approximate values)
   - `12.3k users` instead of `12,345 users` (when showing high-level metrics)

9. **When to Use Abbreviations**: Use abbreviated formats (k/m/b) when:
   - Displaying dashboard KPIs or summary statistics
   - The exact number is not critical for the user's understanding
   - Space is limited (e.g., cards, badges, compact views)
   - The number is very large and the precision doesn't add value

10. **When to Use Full Numbers**: Display full numbers when:
    - The exact value is important (e.g., account balances, transaction amounts)
    - Users need to see precise values for decision-making
    - The number is small enough that abbreviation doesn't help readability

## Percentage Display

11. **Percentage Formatting**: Format percentages consistently:
    - Use one decimal place when appropriate: `45.7%`
    - Use whole numbers when the decimal doesn't add value: `50%` instead of `50.0%`
    - Always include the `%` symbol

## Consistency

12. **Maintain Consistency**: Within a single screen or context, use consistent formatting:
    - If you abbreviate one KPI with `k` or `m`, consider abbreviating similar KPIs
    - Use the same decimal precision for similar types of numbers
    - Keep currency formatting consistent across all currency displays

## Accessibility

13. **Screen Reader Considerations**: When using abbreviations like `k` or `m`, ensure screen readers can properly announce them:
    - Use `aria-label` or `title` attributes to provide full text when needed
    - Consider using visually hidden text for screen readers: `<span aria-hidden="true">1.2k</span><span class="sr-only">1,200</span>`