Value Formatting

Format displayed numbers with thousands separators, compact notation, or currency symbols. Raw values are preserved for calculations; only display output is affected.

Format Options

Thousands Separators

Add commas to large numbers:

charts:
  revenue:
    type: line
    lines: false
    title: Monthly Revenue
    format:
      thousands: true
    file: charts/revenue.csv

Result: 1234567 → 1,234,567

Compact Notation

Shorten large numbers with K/M/B suffixes:

charts:
  users:
    type: stacked-bar
    title: User Growth
    format:
      compact: true
    file: charts/users.csv

Examples:

• 1500 → 1.5K
• 2000000 → 2M
• 3500000000 → 3.5B

Compact notation defaults to 1 decimal place. Override with decimals:

format:
  compact: true
  decimals: 0  # 1500 → 2K (rounded)

Currency Symbols

Add currency prefix or suffix:

charts:
  sales:
    type: line
    lines: false
    title: Sales by Region
    format:
      thousands: true
      currency:
        symbol: "$"
    file: charts/sales.csv

Result: 1234 → $1,234

Suffix Position

For currencies that follow the number (e.g., Euro in some locales):

format:
  thousands: true
  currency:
    symbol: "€"
    position: suffix

Result: 1234 → 1,234€

Decimal Places

Control precision with decimals:

format:
  decimals: 2

Works with all formatting options:

format:
  thousands: true
  decimals: 2
  currency:
    symbol: "$"
# 1234.5 → $1,234.50

Scatter and Bubble Chart Formatting

Scatter and bubble charts support separate formatting for X, Y, and size dimensions. Use the axis-specific format objects:

charts:
  scatter:
    type: scatter
    file: charts/data.csv
    x:
      format:
        thousands: true
    y:
      format:
        compact: true
        currency:
          symbol: "$"

This applies different formatting to each axis independently.

Size Formatting

For scatter and bubble charts with a size dimension, format the size values and legend:

charts:
  bubble:
    type: bubble
    file: charts/data.csv
    size:
      column: magnitude
      title: Magnitude
      format:
        decimals: 1

Global Format Fallback

You can also set a global format as fallback and override specific axes:

charts:
  scatter:
    type: scatter
    format:
      thousands: true    # default for both axes
    x:
      format:
        compact: true    # override for X axis only

Combining Options

Multiple formatting options can be combined:

format:
  thousands: true      # Add commas
  compact: true        # Use K/M/B (overrides thousands for large numbers)
  decimals: 1          # One decimal place
  currency:
    symbol: "$"        # Dollar sign prefix

Note: When both thousands and compact are true, compact takes precedence for numbers large enough to abbreviate.