Format

formatNumber

formatNumber(value: number | bigint, options: FormatNumberOptions): string

formatNumber formats an exact number, such as a count or a total, in the reader's locale. It groups thousands always, so Spanish writes "1.204" as Portuguese does, where Intl alone would leave four-digit numbers ungrouped. Other Intl.NumberFormat options pass through.

Returns string

The number as the reader writes it: "1,204", "1.204".

formatCompactNumber

formatCompactNumber(value: number, options: FormatCompactNumberOptions): string

formatCompactNumber shortens a large number for Stat Tile and chart axes only: "1.2K", "1,2 mil". Tables and counts use formatNumber, which keeps every digit.

Returns string

The short form of the number.

formatDate

formatDate(value: DateValue, options: FormatDateOptions): string

formatDate formats the date of an absolute moment in the reader's time zone: "27/10/2026" in pt-BR, "10/27/2026" in en-US, with style: "medium" "27 de out. de 2026". For a date that has no moment, such as an expiry, use formatCalendarDate.

Returns string

The date, or an empty string when `value` is not a moment.

formatDateTime

formatDateTime(value: DateValue, options: FormatDateTimeOptions): string

formatDateTime formats an absolute moment, date and time, in the reader's time zone. The default style joins the numeric date and the time with a space: "27/10/2026 15:05" in pt-BR, "10/27/2026 3:05 PM" in en-US. The clock follows the locale unless hourCycle forces one.

Returns string

The date and time, or an empty string when `value` is not a moment.

formatTime

formatTime(value: DateValue, options: FormatTimeOptions): string

formatTime formats the time of an absolute moment in the reader's time zone: "15:05" in pt-BR, "3:05 PM" in en-US.

Returns string

The time, or an empty string when `value` is not a moment.

formatCalendarDate

formatCalendarDate(value: string, options: FormatCalendarDateOptions): string

formatCalendarDate formats a date that has no moment, such as an expiry or a filter's date, written YYYY-MM-DD. It converts no time zone, so the day never moves: "2026-10-27" is "27/10/2026" wherever it runs.

Returns string

The date, or an empty string when `value` is not a valid date.

formatRelativeTime

formatRelativeTime(value: DateValue, options: FormatRelativeTimeOptions): string

formatRelativeTime says how long ago or how soon a moment is, for freshness only: "2 hours ago", "há 2 horas", "yesterday". It counts whole units of the largest unit that fits. Show the absolute moment beside it, or in a tooltip, wherever the exact time matters.

Returns string

The distance in words, or an empty string when `value` is not a moment.

selectPlural

selectPlural(count: number, forms: PluralForms<T>, options: LocaleOptions): T

selectPlural picks the form of a text for a count, by the plural rules of the reader's language: one and other in English and Portuguese, more in other languages. Use it in a label function, with the forms from the app's dictionary. Format the count itself with formatNumber.

Returns T

The form for the count, or `other` when that category is missing.

LocaleOptions

LocaleOptions holds the reader's language, a BCP 47 tag such as pt-BR.

ZonedOptions

LocaleOptions & {
  /** The IANA name of the reader's time zone: `America/Sao_Paulo`. */
  timeZone: string
}

ZonedOptions adds the reader's time zone, for absolute moments.

DateStyle

"short" | "medium" | "long"

DateStyle picks how a date reads. short (the default) is the numeric date of lists and tables, with a four-digit year: 27/10/2026, 10/27/2026. medium and long spell the month, for prose and headers: 27 de out. de 2026, October 27, 2026.

TimeOptions

TimeOptions sets how the time of a moment reads.

DateValue

Date | number | string

DateValue is a moment: a Date, epoch milliseconds, or an ISO string with a time and an offset (2026-10-27T18:05:09Z). A date with no time, such as 2026-10-27, is not a moment: format it with formatCalendarDate.

FormatNumberOptions

LocaleOptions &
  Omit<Intl.NumberFormatOptions, "localeMatcher">

FormatNumberOptions are Intl.NumberFormat options plus the locale.

FormatCompactNumberOptions

LocaleOptions & {
  /** Digits after the decimal separator, 1 by default: "1,2 mil". */
  maximumFractionDigits?: number
}

FormatCompactNumberOptions are the options of formatCompactNumber.

FormatDateOptions

ZonedOptions & {
  /** How the date reads. `short` by default. */
  style?: DateStyle
}

FormatDateOptions are the options of formatDate.

FormatDateTimeOptions

FormatDateOptions & TimeOptions

FormatDateTimeOptions are the options of formatDateTime.

FormatTimeOptions

ZonedOptions & TimeOptions

FormatTimeOptions are the options of formatTime.

FormatCalendarDateOptions

LocaleOptions & {
  /** How the date reads. `short` by default. */
  style?: DateStyle
}

FormatCalendarDateOptions are the options of formatCalendarDate.

FormatRelativeTimeOptions

LocaleOptions & {
  /**
   * The moment to measure from, usually the current time. It is required, so
   * the function stays pure and renders the same on the server and the client.
   */
  now: Date | number
  /** The length of the unit names: `long` (the default), `short` or `narrow`. */
  style?: Intl.RelativeTimeFormatStyle
}

FormatRelativeTimeOptions are the options of formatRelativeTime.

PluralForms

Partial<Record<Intl.LDMLPluralRule, T>> & {
  other: T
}

PluralForms holds the forms of one text, one per plural category the reader's language has (Intl.PluralRules). other is required: it is the form every language has, and the one used when a category is missing.