Display formatters

String formatters for UI output. Numeric value formatters accept Decimal.Value (string, number, bigint, Decimal) so call sites don’t need to convert.


import {
  formatCompact,
  formatCompactCurrency,
  formatCurrency,
  formatDynamicDecimals,
  formatPercentage,
  formatRelativeTimestamp,
  formatWithCommas,
} from "@symmio/utils/format";

`formatWithCommas`

Thousand separators with configurable decimal handling.


formatWithCommas(1234.4, { fixedDecimals: 4 }); // "1,234.4000"
formatWithCommas(1234.123456, { maxDecimals: 5 }); // "1,234.12345"
formatWithCommas(0.000123, { dynamicDecimals: 2 }); // "0.00012"
formatWithCommas(undefined); // "0"

Options


interface FormatWithCommasOptions {
  maxDecimals?: number; // cap; trailing zeros stripped
  fixedDecimals?: number; // exact, padded with zeros — wins over maxDecimals
  dynamicDecimals?: number; // significant digits after first non-zero
  rounding?: RoundingMode; // default ROUND_DOWN
}

`formatCurrency`

USD currency wrapper around formatWithCommas.


formatCurrency(1234.5); // "$1,234.5"
formatCurrency(1234.5, { display: "code" }); // "1,234.5 USD"
formatCurrency(1234.5, { display: "symbol-code" }); // "$1,234.5 USD"
formatCurrency(0.000123, { dynamicDecimals: 2 }); // "$0.00012"

`formatCompact`

K / M / B / T / Q notation.


formatCompact(1500); // "1.5K"
formatCompact(1_500_000); // "1.5M"
formatCompact(12_345_678, { maxDecimals: 1 }); // "12.3M"
formatCompact(1500, { threshold: "M" }); // "1,500" — under threshold

`formatCompactCurrency`

Compact notation plus the $ / USD decoration.


formatCompactCurrency(1_500_000); // "$1.5M"
formatCompactCurrency(1_500_000, { display: "code" }); // "1.5M USD"
formatCompactCurrency(-1_234_567, { maxDecimals: 1 }); // "-$1.2M"

`formatPercentage`

Percentage with optional sign and thousand separators. Input is the percentage itself (54 for “54%”), not a ratio.


formatPercentage(54); // "54%"
formatPercentage(54, { withSign: true }); // "+54%"
formatPercentage(-54, { withSign: true }); // "-54%"
formatPercentage(54.1, { fixedDecimals: 2 }); // "54.10%"
formatPercentage(12345.6, { fixedDecimals: 2 }); // "12,345.60%"
formatPercentage(0); // "0%"

`formatDynamicDecimals`

Adaptive precision: show sig significant digits after the first non-zero, no trailing zeros.


formatDynamicDecimals(0.000123, 2); // "0.00012"
formatDynamicDecimals(0.000001223, 2); // "0.0000012"
formatDynamicDecimals(1223.12321, 2); // "1223.12"
formatDynamicDecimals(0.1, 2); // "0.1"
formatDynamicDecimals(0.0000123456, 3, { maxDecimals: 6 }); // "0.000012"

Useful for prices that span many orders of magnitude (think shitcoin tickers and stablecoins in the same UI).

`formatRelativeTimestamp`

Short relative labels for Unix timestamps in seconds.


formatRelativeTimestamp(1_700_000_060n, { nowSeconds: 1_700_000_000 }); // "in 1m"
formatRelativeTimestamp(1_699_999_940n, { nowSeconds: 1_700_000_000 }); // "1m ago"
formatRelativeTimestamp(0n); // "Not set"

Use options for product-specific wording:


formatRelativeTimestamp(expiryTimestamp, {
  nowLabel: "expires now",
  formatFuture: (duration) => `expires in ${duration}`,
  formatPast: (duration) => `expired ${duration} ago`,
});