useTimeAgo

v0.0.15testeddemo

Reactive relative time string (e.g. `'3 minutes ago'`) that ticks on a fixed interval. Fully customizable messages (i18n), units, rounding, and an automatic fallback to a full date once `max` is exceeded.

Source Tests

Examples

const timeAgo = useTimeAgo(new Date(Date.now() - 60_000)); // '1 minute ago'

// With pause/resume controls and a custom update cadence
const { timeAgo, pause, resume } = useTimeAgo(date, { controls: true, updateInterval: 1000 });

// i18n + full-date fallback past one month
const timeAgo = useTimeAgo(date, {
  max: 'month',
  messages: { ...customMessages },
  fullDateFormatter: d => d.toLocaleDateString('fr-FR'),
});

Demo

Loading demo…

Signatures

export function useTimeAgo<UnitNames extends string = UseTimeAgoUnitName>(
  time: MaybeRefOrGetter<Date | number | string>,
  options?: UseTimeAgoOptions<false, UnitNames>,
): ComputedRef<string>;

export function useTimeAgo<UnitNames extends string = UseTimeAgoUnitName>(
  time: MaybeRefOrGetter<Date | number | string>,
  options: UseTimeAgoOptions<true, UnitNames>,
): UseTimeAgoControls;

Type Parameters

UnitNamesextends string= UseTimeAgoUnitName

Parameters

Parameter	Type	Default	Description
`time`	`MaybeRefOrGetter<string \| number \| Date>`	—	The instant to describe (reactive)
`options`?	`UseTimeAgoOptions<boolean, UnitNames>`	`{}`	Options

Returns

ComputedRef<string> | UseTimeAgoControlsThe reactive string, or controls when `controls: true`