use-time-ago

Format the distance between two instants as a localized relative phrase.


Package	`@vizejs/composable/use-time-ago`
Own the source	`vize lib pull composable:use-time-ago`
Runtime exports	`formatTimeAgo`, `useTimeAgo`
Gzip budget	4352 B

Usage

import { formatTimeAgo, useTimeAgo } from "@vizejs/composable/use-time-ago";

Runtime contract

Utility	Category	Stability	SSR	Hydration	Cleanup	Targets	Host globals	Uses
`formatTimeAgo`	i18n	experimental	safe	stable	none	web, server, worker, native, desktop, terminal	`Intl`	—
`useTimeAgo`	i18n	experimental	deterministic-fallback	caller-managed	caller, reactive-scope	web, server, worker, native, desktop, terminal	`globalThis`, `Intl`, `window`	`formatTimeAgo`, `useTimestamp`

API

`formatTimeAgo`

Format the distance between two instants as a localized relative phrase. Pure and deterministic: the output depends only on the arguments (the locale defaults to "en", never the host default), which makes it safe for server rendering and hydration.

function formatTimeAgo( time: TimeAgoInput, now: TimeAgoInput, options: FormatTimeAgoOptions = {}, ): string

formatTimeAgo(Date.UTC(2026, 0, 1), Date.UTC(2026, 0, 2)); // "yesterday"
formatTimeAgo(0, 90_000, { numeric: "always" }); // "2 minutes ago"

`useTimeAgo`

Reactive localized "time ago" phrase that refreshes on an interval. Combines formatTimeAgo with a pausable clock. For SSR, inject initialNow (the server render time) and a fixed locale: both sides then produce the same phrase and the client clock takes over on its first tick. No timer runs on the server; the timer stops with the owning scope.

function useTimeAgo( time: MaybeRefOrGetter<TimeAgoInput>, options?: UseTimeAgoOptions<false>, ): ComputedRef<string>

const phrase = useTimeAgo(() => post.value.createdAt, { locale: useLocale().locale });

`useTimeAgo`

function useTimeAgo( time: MaybeRefOrGetter<TimeAgoInput>, options: UseTimeAgoOptions<true>, ): TimeAgoControls

`useTimeAgo`

function useTimeAgo( time: MaybeRefOrGetter<TimeAgoInput>, options: UseTimeAgoOptions<boolean> = {}, ): ComputedRef<string> | TimeAgoControls

Types

`FormatTimeAgoOptions`

Options for formatTimeAgo.

Member	Type	Description
`locale`?	`string \| readonly string[]`	BCP 47 locale(s) for `Intl.RelativeTimeFormat`. Defaults to a fixed locale (not the host default) so server and client output agree.
`numeric`?	`"always" \| "auto"`	`"auto"` allows phrases such as "yesterday" and "now"; `"always"` keeps numeric output such as "1 day ago".
`style`?	`"long" \| "short" \| "narrow"`	Length of the unit wording.
`units`?	`readonly TimeAgoUnit[]`	Units allowed in the output, in any order. The largest allowed unit that fits the distance wins; smaller distances use the smallest unit.
`rounding`?	`"round" \| "floor" \| "ceil"`	How a fractional unit count becomes an integer.
`justNowMs`?	`number`	Distances below this many milliseconds are reported as zero of the smallest unit ("now" with `numeric: "auto"`).
`maxMs`?	`number`	Distances of at least this many milliseconds are delegated to `FormatTimeAgoOptions.fullDateFormatter`.
`fullDateFormatter`?	`(date: Date) => string`	Formats dates beyond `FormatTimeAgoOptions.maxMs`.

`UseTimeAgoOptions`

Options for useTimeAgo.

Member	Type	Description
`locale`?	`MaybeRefOrGetter<string \| readonly string[]>`	Reactive BCP 47 locale(s). Pair with `useLocale()` to follow the user.
`updateIntervalMs`?	`MaybeRefOrGetter<number>`	How often the relative phrase is recomputed, in milliseconds.
`now`?	`() => number`	Clock source returning Unix epoch milliseconds.
`initialNow`?	`number`	Hydration-stable "now" used for the first render on server and client.
`runOnServer`?	`boolean`	Starts host timers when no browser `window` is available.
`scheduler`?	`IntervalScheduler`	Repeating timer host.
`controls`?	`Controls`	Return the full control object instead of the bare phrase ref.

`TimeAgoControls`

Phrase and controls returned by useTimeAgo(time, { controls: true }).

Member	Type	Description
`isActive`	`Readonly<ShallowRef<boolean>>`	Whether the timer is logically running. On the server (without `runOnServer`) this reflects the requested state without starting a host timer, so server and client render the same initial value.
`pause`	`() => void`	Stop ticking. Idempotent.
`resume`	`() => void`	Start (or keep) ticking. Idempotent.
`timeAgo`	`ComputedRef<string>`	Localized relative phrase such as "3 minutes ago".
`now`	`Readonly<ShallowRef<number>>`	The reference "now" in Unix epoch milliseconds.