useTimeAgo

Returns a ReadonlyObservable<string> with a human-readable relative time string (e.g. “5 minutes ago”, “in 2 days”) that auto-updates at a configurable interval.

Formatting is delegated to date-fns/formatDistance, enabling full i18n locale support.

Also exports formatTimeAgo as a standalone pure function for one-off formatting.

Demo

just now

0ms

Usage

import { useTimeAgo } from "@usels/web";

const timeAgo = useTimeAgo(new Date("2024-01-01"));
// timeAgo.get() → "about 3 months ago"

Reactive time

import { useTimeAgo } from "@usels/web";
import { observable } from "@legendapp/state";

const time$ = observable(new Date());
const timeAgo = useTimeAgo(time$);

time$.set(new Date("2020-01-01")); // → "about 4 years ago"

With pause/resume controls

import { useTimeAgo } from "@usels/web";

const { timeAgo$, isActive$, pause, resume } = useTimeAgo(new Date(), {
  controls: true,
});

Custom update interval

import { useTimeAgo } from "@usels/web";

// Update every 10 seconds instead of every 30
const timeAgo = useTimeAgo(new Date(), { updateInterval: 10_000 });

Show seconds

When showSecond: true, times under 1 minute are shown in detail (maps to date-fns includeSeconds). When showSecond: false (default), times within 45 s show "just now".

import { useTimeAgo } from "@usels/web";

const timeAgo = useTimeAgo(new Date(Date.now() - 30_000), { showSecond: true });
// → "half a minute ago"

Limit with max

import { useTimeAgo } from "@usels/web";

const timeAgo = useTimeAgo(new Date("2020-01-01"), {
  max: "month",
  fullDateFormatter: (d) => d.toLocaleDateString(),
});
// dates older than ~11 months → formatted date string

i18n with date-fns locale

Pass any date-fns locale to the locale option.

import { useTimeAgo } from "@usels/web";
import { ko } from "date-fns/locale";

const timeAgo = useTimeAgo(new Date(), { locale: ko });
// → "방금 전"

import { useTimeAgo } from "@usels/web";
import { ja } from "date-fns/locale";

const timeAgo = useTimeAgo(new Date("2024-01-01"), { locale: ja });
// → "約1年前"

You can also use formatTimeAgo with a locale:

import { formatTimeAgo } from "@usels/web";
import { fr } from "date-fns/locale";

const str = formatTimeAgo(new Date("2024-01-01"), { locale: fr }, new Date("2024-06-01"));
// → "il y a environ 5 mois"

formatTimeAgo — pure function

import { formatTimeAgo } from "@usels/web";

const str = formatTimeAgo(new Date("2024-01-01"), {}, new Date("2024-06-01"));
// → "about 5 months ago"

Type Declarations

export type UseTimeAgoUnitNamesDefault = "second" | "minute" | "hour" | "day" | "week" | "month" | "year";
export interface UseTimeAgoOptions<Controls extends boolean = false> {
    controls?: Controls;
    updateInterval?: number;
    locale?: Locale;
    max?: UseTimeAgoUnitNamesDefault | number;
    fullDateFormatter?: (date: Date) => string;
    showSecond?: boolean;
}
export interface FormatTimeAgoOptions {
    locale?: Locale;
    max?: UseTimeAgoUnitNamesDefault | number;
    fullDateFormatter?: (date: Date) => string;
    showSecond?: boolean;
}
export declare function formatTimeAgo(from: Date, options?: FormatTimeAgoOptions, now?: Date | number): string;
export declare function useTimeAgo(time: MaybeObservable<Date | number | string>, options?: UseTimeAgoOptions<false>): ReadonlyObservable<string>;
export declare function useTimeAgo(time: MaybeObservable<Date | number | string>, options: UseTimeAgoOptions<true>): {
    timeAgo$: ReadonlyObservable<string>;
} & Pausable;

Source

View on GitHub

Contributors

• tigerwest

Changelog

• a7392ab 2026-03-06 - feat(core,browser): add sync strategy hooks (tigerwest)