use-relative-time-format

Pick the largest unit that expresses a millisecond difference as a non-zero rounded amount: seconds below a minute, minutes below an hour, hours below a day, days below a week, weeks below a month, months below a year, and years otherwise (Gregorian average month/year lengths).


Package	`@vizejs/composable/use-relative-time-format`
Own the source	`vize lib pull composable:use-relative-time-format`
Runtime exports	`selectRelativeTimeUnit`, `useRelativeTimeFormat`
Gzip budget	3072 B

Usage

import { selectRelativeTimeUnit, useRelativeTimeFormat } from "@vizejs/composable/use-relative-time-format";

Runtime contract

Utility	Category	Stability	SSR	Hydration	Cleanup	Targets	Host globals	Uses
`selectRelativeTimeUnit`	i18n	experimental	safe	not-applicable	none	web, server, worker, native, desktop, terminal	—	—
`useRelativeTimeFormat`	i18n	experimental	deterministic-fallback	caller-managed	none	web, server, worker, native, desktop, terminal	`Date`, `Intl`, `window`	`selectRelativeTimeUnit`, `useLocale`

API

`selectRelativeTimeUnit`

function selectRelativeTimeUnit(diffMs: number): RelativeTimeValue

`useRelativeTimeFormat`

Format relative times ("in 3 days", "yesterday") with Intl.RelativeTimeFormat. A pure formatting wrapper: it owns no clock or timer, so it never re-renders on its own and stays deterministic during server rendering (pair it with a clock composable for live "time ago" labels). The formatter follows the reactive options and is cached per locale and option set through useLocale; invalid options surface as the platform's RangeError.

function useRelativeTimeFormat( value: MaybeRefOrGetter<number | null | undefined>, unit: MaybeRefOrGetter<Intl.RelativeTimeFormatUnit>, options: MaybeRefOrGetter<UseRelativeTimeFormatOptions> = {}, ): RelativeTimeFormatControls

const { formatted } = useRelativeTimeFormat(-1, "day", { locale: "en", numeric: "auto" });
formatted.value; // "yesterday"

Types

`RelativeTimeValue`

A signed amount in one relative-time unit.

Member	Type	Description
`value`	`number`	Signed, rounded amount; negative values are in the past.
`unit`	`RelativeTimeUnitSelection`	Unit the amount is expressed in.

`UseRelativeTimeFormatOptions`

Options for useRelativeTimeFormat.

Member	Type	Description
`locale`?	`string \| Intl.Locale`	Locale used for formatting. Pass it explicitly for hydration-stable server rendering.

`RelativeTimeFromOptions`

Options for RelativeTimeFormatControls.formatFrom.

Member	Type	Description
`now`?	`number`	Reference time in Unix milliseconds. Pass it explicitly to keep server and client output identical.

`RelativeTimeFormatControls`

Reactive relative-time formatting returned by useRelativeTimeFormat.

Member	Type	Description
`locale`	`ComputedRef<string>`	Canonical locale in use.
`formatter`	`ComputedRef<Intl.RelativeTimeFormat>`	Cached formatter for the current locale and options.
`formatted`	`ComputedRef<string>`	Formatted `value` in `unit`, or `""` while either is missing.
`format`	`(value: number, unit: Intl.RelativeTimeFormatUnit) => string`	Format an amount in a unit.
`formatToParts`	`( value: number, unit: Intl.RelativeTimeFormatUnit, ) => Intl.RelativeTimeFormatPart[]`	Format an amount in a unit into parts.
`formatDiff`	`(diffMs: number) => string`	Format a signed millisecond difference using the best-fitting unit (see `selectRelativeTimeUnit`).
`formatFrom`	`(date: Date \| number, options?: RelativeTimeFromOptions) => string`	Format a date relative to a reference time using the best-fitting unit.