Numbers and currency

Numbers#

formatNumber(value, format, presentation). Precision, notation and sign come from format; separators, grouping and digits come from the presentation.

• A preset: 'integer', 'decimal', 'decimal-1', 'decimal-2', 'decimal-4' or 'compact'.

• Or a NumberSpec: decimals or significant digits (the type refuses both), plus a notation (standard, scientific, engineering, compact) and a sign display.

An out-of-range or inconsistent specification throws a RangeError; it is never clamped.

Currency amounts#

formatCurrency({amount, currency}, presentation, options?).

• The currency comes from the data, never from the language. 'EUR' in an English text is still euros.

• Decimals follow the currency's minor units (EUR 2, JPY 0, KWD 3), rounded half away from zero. Override them only as a deliberate presentation choice, with decimals.

• Exact amounts: pass a DecimalString (from toDecimalString) and the digits reach Intl as that exact decimal, never through a floating-point number.

• A localised string such as '1.234,56' is user input, not an amount: read it with classifyNumberInput first.

// apps/docs/examples/format/currency-amounts.tsx'use client';
import {formatCurrency, toDecimalString} from '@workspace/active-format';import {  Table,  TableBody,  TableCell,  TableRow,} from '@workspace/active-ui/components/primitives/table';
const EXACT = '12345678901234567.89';
/** * The currency comes from the data, the notation from the presentation. * Decimals follow the currency's minor units unless the call overrides them. */export default function CurrencyAmounts() {  const rows: [string, string][] = [    ['EUR, en', formatCurrency({amount: 1234.5, currency: 'EUR'}, 'en')],    ['EUR, nl', formatCurrency({amount: 1234.5, currency: 'EUR'}, 'nl')],    [      'JPY (no minor unit)',      formatCurrency({amount: 1234.5, currency: 'JPY'}, 'en'),    ],    [      'KWD (three decimals)',      formatCurrency({amount: 1234.5, currency: 'KWD'}, 'en'),    ],    [      'Whole amounts',      formatCurrency({amount: 1234.5, currency: 'EUR'}, 'en', {decimals: 0}),    ],    [      'A change, signed',      formatCurrency({amount: 12.5, currency: 'EUR'}, 'en', {        sign: 'exceptZero',      }),    ],    [      'Exact decimal string',      formatCurrency({amount: toDecimalString(EXACT), currency: 'EUR'}, 'en'),    ],    [      'The same value as a number',      formatCurrency({amount: Number(EXACT), currency: 'EUR'}, 'en'),    ],    [      'No amount',      formatCurrency({amount: null, currency: 'EUR'}, 'en') || '(empty string)',    ],  ];  return (    <Table>      <TableBody>        {rows.map(([label, text]) => (          <TableRow key={label}>            <TableCell className="text-muted-foreground">{label}</TableCell>            <TableCell className="font-mono">              <output suppressHydrationWarning>{text}</output>            </TableCell>          </TableRow>        ))}      </TableBody>    </Table>  );}

Use UNKNOWN_CURRENCY ('XXX') only for an amount whose currency cannot be established, never as a substitute for a currency you could know.

Percentages#

The stored form decides the function:

• formatFractionAsPercent(0.125, 'decimal-1', presentation): the value is a fraction; 0.125 is 12.5 %.

• formatPercentagePoints(12.5, 'decimal-1', presentation): the value is in points; 12.5 is 12.5 %.

Units, sizes and durations#

• formatUnit(value, unit, presentation, options?): a measured quantity in the unit you supply, never converted.

• formatByteSize(bytes, presentation, {system}): a count of bytes. The system is required, because decimal (1000) and binary (1024) differ by up to 12.6 %.

  Fields

  systemrequired

  Type

  ByteSizeSystem

  The scale: decimal (1000, SI units kB … PB) or binary (1024, IEC units KiB … PiB). Required: the two differ by 2.4% at kilo and 12.6% at peta, and a reader cannot tell which one a bare KB meant.

  maxDecimals

  Type

  number

  The largest number of decimals shown, an integer from 0 to 20; trailing zeros are dropped (1.5, not 1.50). Default 1, owned by this package. A whole number of bytes never shows decimals.

• formatElapsedDuration(value, inputUnit, presentation, options): an elapsed duration in fixed units, from milliseconds to days of exactly 24 hours, never months. It needs Intl.DurationFormat and throws without it.

Lists and ranges#

• formatList(items, presentation, options?) joins your own text in the reader's language (Amsterdam, Utrecht and Delft).

• formatNumberRange(start, end, format, presentation) and formatDateOnlyRange(start, end, preset, presentation) write a range with the language's own range separator. A start after its end, or a missing bound, gives ''.

Empty and invalid values#

An empty value (null, undefined, '', and NaN or ±Infinity for numbers) and an unreadable value return ''. Your interface chooses and translates its own placeholder. A programming or configuration error, such as an unknown unit or an invalid decimals, throws.