Number Format
Locale-aware number, currency, percentage, and compact formatter using Intl.NumberFormat.
<arc-number-format>Overview
NumberFormat renders a formatted number using the browser's built-in Intl.NumberFormat API, providing locale-aware formatting for numbers, currencies, percentages, and compact notation. Pass a raw numeric value and a type, and the component handles thousands separators, currency symbols, percent signs, and compact suffixes like "12.3K" or "1.2M".
The component uses font-variant-numeric: tabular-nums and the monospace font stack so that formatted numbers align vertically in tables, stat grids, and dashboards. Because formatting is handled entirely via Intl.NumberFormat, it respects the user's locale conventions (decimal commas in Germany, lakh grouping in India, yen symbol placement in Japan) with no configuration beyond the locale prop.
For the percent type, values are treated as the actual percentage: pass 50 to display "50%", not 0.5. This avoids the Intl.NumberFormat footgun where the percent style multiplies by 100.
Guidelines
When to use
- Use in tables and stat cards where numbers need to align vertically
- Set type="currency" with the appropriate currency code for financial data
- Use notation="compact" for large numbers in space-constrained layouts
- Pair with AnimatedNumber for values that change over time
- Set locale explicitly when building multi-language applications
When not to use
- Do not use for animated counting effects; use AnimatedNumber instead
- Do not wrap in additional monospace styling: the component already uses tabular-nums
- Do not pass 0.5 for 50%: the percent type expects the actual percentage value (50)
- Do not forget to set the currency prop when using type="currency" in non-USD contexts
Features
- Locale-aware formatting via Intl.NumberFormat for numbers, currency, percent, and compact notation
- Tabular nums and monospace font for vertical alignment in grids and tables
- Compact notation renders "12.3K", "1.2M", "4.5B" for large numbers
- Percent type treats values as actual percentages (50 = 50%)
- Configurable decimal places, with defaults per type
- Supports any BCP 47 locale and ISO 4217 currency code
- Minimal styling: inherits size and color from parent context
Preview
Number: 1,234,567
Currency: $1,234.50
Percent: 99.9%
Compact: 1M
Usage
<!-- Basic number with thousands separators -->
<arc-number-format value="1234567"></arc-number-format>
<!-- Currency -->
<arc-number-format value="1234.50" type="currency" currency="USD"></arc-number-format>
<!-- Percentage (50 = 50%) -->
<arc-number-format value="99.9" type="percent"></arc-number-format>
<!-- Compact notation -->
<arc-number-format value="1234567" notation="compact"></arc-number-format>
<!-- European locale -->
<arc-number-format value="1234.56" type="currency" currency="EUR" locale="de-DE"></arc-number-format>import { NumberFormat } from '@arclux/arc-ui-react';
function PricingTable({ price, change, users }) {
return (
<div>
<NumberFormat value={price} type="currency" />
<NumberFormat value={change} type="percent" />
<NumberFormat value={users} notation="compact" />
</div>
);
}<script setup>
import { NumberFormat } from '@arclux/arc-ui-vue';
const price = 1234.50;
const change = 12.5;
</script>
<template>
<NumberFormat :value="price" type="currency" />
<NumberFormat :value="change" type="percent" />
</template><script>
import { NumberFormat } from '@arclux/arc-ui-svelte';
let price = 1234.50;
let change = 12.5;
</script>
<NumberFormat value={price} type="currency" />
<NumberFormat value={change} type="percent" />import { Component } from '@angular/core';
import { NumberFormat } from '@arclux/arc-ui-angular';
@Component({
imports: [NumberFormat],
template: `
<arc-number-format [value]="price" type="currency" />
<arc-number-format [value]="change" type="percent" />
`,
})
export class MetricsComponent {
price = 1234.50;
change = 12.5;
}import { NumberFormat } from '@arclux/arc-ui-solid';
function Metrics() {
return (
<div>
<NumberFormat value={1234.50} type="currency" />
<NumberFormat value={12.5} type="percent" />
</div>
);
}import { NumberFormat } from '@arclux/arc-ui-preact';
function Metrics() {
return (
<div>
<NumberFormat value={1234.50} type="currency" />
<NumberFormat value={12.5} type="percent" />
</div>
);
}API
localestring'en-US'- BCP 47 locale tag for locale-aware formatting
currencystring'USD'- ISO 4217 currency code, used when type is "currency"
valuenumber0- The number to format
type'number' | 'currency' | 'percent' | 'compact''number'- Formatting style to apply
decimalsnumber0- Number of decimal places, 0 to 20 (
Intl.NumberFormat's own range). Unset uses a per-format default: 0 for number, 2 for currency, 1 for percent. notation'standard' | 'compact''standard'- Number notation: compact gives "12.3K", "1.2M"