Format Number

A utility component for formatting numbers with locale-aware styling. Supports decimal, currency, percentage, and unit formats using the Intl.NumberFormat API.

Anatomy

<script>
  import { FormatNumber } from "@saas-ui/svelte/utilities/format-number";
</script>

<!-- Basic decimal -->
<FormatNumber value={1234.56} />

<!-- Currency format -->
<FormatNumber value={1234.56} style="currency" currency="USD" />

<!-- Percentage -->
<FormatNumber value={0.75} style="percent" />

<!-- With locale -->
<FormatNumber value={1234.56} locale="de-DE" />

<!-- Compact notation -->
<FormatNumber value={1000000} notation="compact" />

Examples

Basic Accessibility

Basic usage showing default decimal number formatting.

<Text size="lg">
	<FormatNumber
		{value}
		{style}
		{currency}
		{unit}
		{minimumFractionDigits}
		{maximumFractionDigits}
		{notation}
		{compactDisplay}
		{locale}
	/>
</Text>

Compact Notation Accessibility

Use notation="compact" to display large numbers in shortened form (e.g., 1M, 1K).

<Text size="lg">
	<FormatNumber
		value={1500000}
		notation="compact"
		compactDisplay="short"
	/>
</Text>

Currency Accessibility

Use style="currency" with the currency prop to format values as monetary amounts.

<Text size="lg">
	<FormatNumber value={1234.45} style="currency" currency="USD" />
</Text>

Locale Accessibility

Use the locale prop to format numbers according to different regional conventions (e.g., decimal separators, grouping).

<Stack>
	<HStack>
		<Text size="md" weight="medium" class="w-16">de-DE</Text>
		<LocaleProvider locale="de-DE">
			<Text size="lg">
				<FormatNumber value={1450.45} />
			</Text>
		</LocaleProvider>
	</HStack>

	<HStack>
		<Text size="md" weight="medium" class="w-16">zh-CN</Text>
		<LocaleProvider locale="zh-CN">
			<Text size="lg">
				<FormatNumber value={1450.45} />
			</Text>
		</LocaleProvider>
	</HStack>
</Stack>

Percentage Accessibility

Use style="percent" to format decimal values as percentages (0.75 becomes 75%).

<Text size="lg">
	<FormatNumber
		value={0.145}
		style="percent"
		maximumFractionDigits={2}
		minimumFractionDigits={2}
	/>
</Text>

Unit Accessibility

Use style="unit" with the unit prop to display numbers with measurement units (e.g., kilometers, liters).

<Text size="lg">
	<FormatNumber value={384.4} style="unit" unit="kilometer" />
</Text>

Props

Prop	Type	Default	Description
`value`	`number`	-	The number to format.
`style`	`decimal \| currency \| percent \| unit`	-	The formatting style to use.
`currency`	`text`	-	The currency to use in currency formatting.
`unit`	`text`	-	The unit to use in unit formatting.
`minimumFractionDigits`	`number`	-	The minimum number of fraction digits to use.
`maximumFractionDigits`	`number`	-	The maximum number of fraction digits to use.
`notation`	`standard \| scientific \| engineering \| compact`	-	The formatting notation to use.
`compactDisplay`	`short \| long`	-	How to display the number in compact notation (only used when notation is compact).
`locale`	`text`	-	The locale to use for formatting. If not provided, uses the locale from LocaleProvider context.