Adding a Number Formatter

The NumberFormatter class provides powerful and flexible number formatting capabilities for your Muze visualizations. Whether you need to display currency, percentages, or decimals with specific precision, NumberFormatter ensures consistent formatting across all chart elements.

Understanding NumberFormatter

NumberFormatter supports three formatting types:

Currency: Display values with currency symbols (e.g., $1,234.56, ₹1,234.56)

Decimal: Display plain numbers with customizable units and precision (e.g., 1.234M)

Percent: Display values as percentages (e.g., 45.67%)

Decimal

The decimal style is ideal for displaying plain numerical values with customizable formatting options like units, separators, and precision.

Auto Unit Scaling

The unit: "auto" option automatically selects the appropriate scale based on the magnitude of your data:

const autoUnitFormatter = new NumberFormatter("decimal", {
    unit: "auto",
    decimalDigits: 2
});

// Examples:
// 1,500,000      → "1.50M"
// 2,500,000,000  → "2.50B"
// 850,000        → "850.00K"

Fixed Unit Scaling

Use fixed units when you want consistent scaling across all values:

// Always display in millions
const millionFormatter = new NumberFormatter("decimal", {
    unit: "millions",
    decimalDigits: 1
});
// Examples: 5,600,000 → "5.6M", 1,234,567 → "1.2M"

// Always display in thousands
const thousandFormatter = new NumberFormatter("decimal", {
    unit: "thousands",
    decimalDigits: 0
});
// Examples: 12,500 → "13K", 8,750 → "9K"

Negative Number Formatting

Control how negative numbers are displayed:

// Prefix dash (default): -1,234.56
const prefixDashFormatter = new NumberFormatter("decimal", {
    negativeSign: "prefixDash",
    decimalDigits: 2
});

// Suffix dash: 1,234.56-
const suffixDashFormatter = new NumberFormatter("decimal", {
    negativeSign: "suffixDash",
    decimalDigits: 2
});

// Parentheses (accounting style): (1,234.56)
const parenthesesFormatter = new NumberFormatter("decimal", {
    negativeSign: "parentheses",
    decimalDigits: 2
});

Thousands separator

Customize separators for thousands grouping:

const thousandsFormatter = new NumberFormatter("decimal", {
    thousandSeparator: "period",
    decimalDigits: 2
});
// 1234.56  →  1,234.56

Decimal separator

Customize separators for decimal places:

const decimalFormatter = new NumberFormatter("decimal", {
    decimalSeparator: "comma",
    decimalDigits: 2
});
// 1234.56  →  1234,56

Complete Example

/**
 * Available Columns:
 * "Category"
 * "Ship Mode"
 * "Total Discount"
 */

const {
    muze,
    getDataFromSearchQuery,
    formatters: {
        NumberFormatter
    }
} = viz;

// Create a currency formatter for Indian Rupees
const discountFormatter = new NumberFormatter("decimal", {
    unit: "auto",
    decimalSeparator: "comma",
    decimalDigits: 2,
});

const data = getDataFromSearchQuery();

muze.canvas()
    .rows(["Ship Mode"])
    .columns(["Category"])
    .layers([{
        mark: "text",
        encoding: {
            text: {
                field: "Total Discount",
                formatter: discountFormatter.formatterFunc()
            }
        }
    }])
    .data(data)
    .mount("#chart");

Currency

The currency style is designed for displaying monetary values with proper currency symbols and formatting conventions.

// US Dollar: $1,234.56
const usdFormatter = new NumberFormatter("currency", {
    currency: "USD",
    decimalDigits: 2
});

// Euro: €1.234,56
const eurFormatter = new NumberFormatter("currency", {
    currency: "EUR",
    decimalDigits: 2
});

// British Pound: £1,234.56
const gbpFormatter = new NumberFormatter("currency", {
    currency: "GBP",
    decimalDigits: 2
});

// Indian Rupee: ₹1,234.56
const inrFormatter = new NumberFormatter("currency", {
    currency: "INR",
    decimalDigits: 2
});

// Japanese Yen: ¥1,235 (typically no decimals)
const jpyFormatter = new NumberFormatter("currency", {
    currency: "JPY",
    decimalDigits: 0
});

// Chinese Yuan: ¥1,234.56
const cnyFormatter = new NumberFormatter("currency", {
    currency: "CNY",
    decimalDigits: 2
});

Auto Unit Scaling

The unit: "auto" option automatically selects the appropriate scale based on the magnitude of your data:

// Currency with auto unit
const autoUnitCurrencyFormatter = new NumberFormatter("currency", {
    currency: "USD",
    unit: "auto",
    decimalDigits: 1
});
// Examples: 1,500,000 → "$1.5M", 2,500,000,000 → "$2.5B"

// Currency with fixed millions unit
const millionCurrencyFormatter = new NumberFormatter("currency", {
    currency: "EUR",
    unit: "millions",
    decimalDigits: 2
});
// Examples: 5,600,000 → "€5.60M", 1,234,567 → "€1.23M"

Negative Currency Values

Handle negative monetary values with different styles:

// Prefix dash (default): -$1,234.56
const prefixDashCurrency = new NumberFormatter("currency", {
    currency: "USD",
    negativeSign: "prefixDash",
    decimalDigits: 2
});

// Parentheses (accounting standard): ($1,234.56)
const parenthesesCurrency = new NumberFormatter("currency", {
    currency: "USD",
    negativeSign: "parentheses",
    decimalDigits: 2
});

Complete Example

/**
 * Available Columns:
 * "Category"
 * "Ship Mode"
 * "Total Discount"
 */

const {
    muze,
    getDataFromSearchQuery,
    formatters: {
        NumberFormatter
    }
} = viz;

// Create a currency formatter for Indian Rupees
const discountFormatter = new NumberFormatter("currency", {
    currency: "INR",
    unit: "auto",
    decimalDigits: 2
});

const data = getDataFromSearchQuery();

muze.canvas()
    .rows(["Ship Mode"])
    .columns(["Category"])
    .layers([{
        mark: "text",
        encoding: {
            text: {
                field: "Total Discount",
                formatter: discountFormatter.formatterFunc()
            }
        }
    }])
    .data(data)
    .mount("#chart");

Percent

The percent style is used for displaying percentage values.

Precision Control

Adjust decimal places based on the level of precision needed:

// Standard precision (2 decimals)
const standardPercent = new NumberFormatter("percent", {
    decimalDigits: 2
});
// Input: 0.1234567 → Output: 12.35%

// High precision (4 decimals)
const precisePercent = new NumberFormatter("percent", {
    decimalDigits: 4
});
// Input: 0.1234567 → Output: 12.3457%

// Whole numbers only (0 decimals)
const wholePercent = new NumberFormatter("percent", {
    decimalDigits: 0
});
// Input: 0.1234567 → Output: 12%

Large Percentages

Handle percentages over 100% with thousands separators:

const largePercentFormatter = new NumberFormatter("percent", {
    decimalDigits: 1,
    thousandSeparator: "comma"
});
// Examples: 12.345 → "1,234.5%", 5.678 → "567.8%"

Negative Percentages

Display negative percentages with different styles:

// Prefix dash (default): -5.60%
const prefixDashPercent = new NumberFormatter("percent", {
    negativeSign: "prefixDash",
    decimalDigits: 2
});

// Parentheses: (5.6%)
const parenthesesPercent = new NumberFormatter("percent", {
    negativeSign: "parentheses",
    decimalDigits: 1
});

// Suffix dash: 5.60%-
const suffixDashPercent = new NumberFormatter("percent", {
    negativeSign: "suffixDash",
    decimalDigits: 2
});

Complete Example

/**
 * Available Columns:
 * "Category"
 * "Ship Mode"
 * "Total Discount"
 */

const {
    muze,
    getDataFromSearchQuery,
    formatters: {
        NumberFormatter
    }
} = viz;

// Create a currency formatter for Indian Rupees
const discountFormatter = new NumberFormatter("percent", {
    unit: "auto",
    thousandSeparator: "comma",
    decimalSeparator: "period",
    decimalDigits: 2,
});

const data = getDataFromSearchQuery();

muze.canvas()
    .rows(["Ship Mode"])
    .columns(["Category"])
    .layers([{
        mark: "text",
        encoding: {
            text: {
                field: "Total Discount",
                formatter: discountFormatter.formatterFunc()
            }
        }
    }])
    .data(data)
    .mount("#chart");

Applying NumberFormatter to Data

/**
 * Available Columns:
 * "Category"
 * "Ship Mode"
 * "Total Discount"
 */

const {
    muze,
    getDataFromSearchQuery,
    formatters: {
        NumberFormatter
    }
} = viz;

// Create a currency formatter for Indian Rupees
const discountFormatter = new NumberFormatter("currency", {
    currency: "INR",
    unit: "auto",
    decimalDigits: 2
});

const data = getDataFromSearchQuery();

muze.canvas()
    .rows(["Ship Mode"])
    .columns(["Category"])
    .layers([{
        mark: "text",
        encoding: {
            text: {
                field: "Total Discount",
                formatter: discountFormatter.formatterFunc()
            }
        }
    }])
    .data(data)
    .mount("#chart");

Applying NumberFormatter to Tooltips

/**
 * Available Columns:
 * "Category"
 * "Total Discount"
 */
 
 const {
    muze,
    getDataFromSearchQuery,
    formatters: {
        NumberFormatter
    }
} = viz;

const discountFormatter = new NumberFormatter("currency", {
    currency: "USD",
    unit: "auto",
    decimalDigits: 2
});

const data = getDataFromSearchQuery();

muze.canvas()
    .rows(["Total Discount"])
    .columns(["Category"])
    .layers([{
        mark: "bar"
    }])
    .config({
        interaction: {
            tooltip: {
                fieldFormatters: {
                    "Total Discount": discountFormatter.formatterFunc()
                }
            }
        }
    })
    .data(data)
    .mount("#chart");

Applying NumberFormatter to Axes

/**
 * Available Columns:
 * "Category"
 * "Total Discount"
 */
 
 const {
    muze,
    getDataFromSearchQuery,
    formatters: {
        NumberFormatter
    }
} = viz;

const discountFormatter = new NumberFormatter("currency", {
    currency: "EUR",
    unit: "auto",
    decimalDigits: 1
});

const data = getDataFromSearchQuery();

muze.canvas()
    .rows(["Total Discount"])
    .columns(["Category"])
    .layers([{
        mark: "bar"
    }])
    .config({
        axes: {
            y: {
                tickFormat: discountFormatter.formatterFunc()
            }
        }
    })
    .data(data)
    .mount("#chart");

Applying NumberFormatter to Facets

/**
 * Available Columns:
 * "Category"
 * "Ship Mode"
 * "Total Discount"
 * --- END --- 
 */

const {
    muze,
    getDataFromSearchQuery,
    formatters: {
        NumberFormatter
    }
} = viz;

const discountFormatter = new NumberFormatter("currency", {
    currency: "INR",
    unit: "auto",
    decimalDigits: 2
});

const data = getDataFromSearchQuery();

muze.canvas()
    .rows([{ field: "Total Discount", as: "discrete" }, "Category"])
    .columns(["Ship Mode"])
    .layers([{
        mark: "bar"
    }])
    .config({
        rows: {
            facets: {
                formatter: (dataInfo) => {
                    return discountFormatter.format(dataInfo.rawValue);
                },
            },
        }
    })
    .data(data)
    .mount("#chart");