use-number-format

Format numbers reactively with Intl.NumberFormat.


Package	`@vizejs/composable/use-number-format`
Own the source	`vize lib pull composable:use-number-format`
Runtime exports	`useNumberFormat`
Gzip budget	2560 B

Usage

import { useNumberFormat } from "@vizejs/composable/use-number-format";

Runtime contract

Utility	Category	Stability	SSR	Hydration	Cleanup	Targets	Host globals	Uses
`useNumberFormat`	i18n	experimental	deterministic-fallback	caller-managed	none	web, server, worker, native, desktop, terminal	`Intl`, `window`	`useLocale`

API

`useNumberFormat`

Format numbers reactively with Intl.NumberFormat. The formatter follows the reactive options (including locale) and is cached per locale and option set through useLocale. Without an explicit locale the browser language is used, falling back to "en" (always the case on the server). Invalid options surface as the platform's RangeError/TypeError on first read. No listeners or timers are created, so nothing needs cleanup.

function useNumberFormat( value?: MaybeRefOrGetter<FormattableNumber | null | undefined>, options: MaybeRefOrGetter<UseNumberFormatOptions> = {}, ): NumberFormatControls

const price = ref(1234.5);
const { formatted } = useNumberFormat(price, { locale: "de-DE", style: "currency", currency: "EUR" });
formatted.value; // "1.234,50 €"

Types

`UseNumberFormatOptions`

Options for useNumberFormat.

Member	Type	Description
`locale`?	`string \| Intl.Locale`	Locale used for formatting. Pass it explicitly for server rendering: without it the server falls back to `"en"` while the browser detects `navigator.language`, which can make hydration mismatch.

`NumberFormatControls`

Reactive number formatting returned by useNumberFormat.

Member	Type	Description
`locale`	`ComputedRef<string>`	Canonical locale in use.
`formatter`	`ComputedRef<Intl.NumberFormat>`	Cached formatter for the current locale and options.
`formatted`	`ComputedRef<string>`	Formatted `value`, or `""` while the value is `null`/`undefined`.
`format`	`(value: FormattableNumber) => string`	Format any number with the current formatter.
`formatToParts`	`(value: FormattableNumber) => Intl.NumberFormatPart[]`	Format any number into locale-aware parts.
`formatRange`	`(start: FormattableNumber, end: FormattableNumber) => string`	Format a numeric range (for example `"3–5"`).