useTimeAgo

Formats the distance between a timestamp and now — “همین الان”, “۵ دقیقه پیش”, “دیروز” — and keeps that string current by re-rendering on an interval. Works with Persian or English messages, and can fall back to an absolute date past a threshold.

Last updated August 12, 2026

Overview

Installation

$ npx shadcn@latest add https://ui.persian-labs.ir/r/use-time-ago.json

Usage

import { useTimeAgo } from "@/hooks/use-time-ago"
 
function LastSeen({ at }: { at: string }) {
  const ago = useTimeAgo(at)
 
  return <span>{ago}</span> // "۲ ساعت پیش"
}

Examples

English locale

Pass locale: "en" to switch to the built-in English message table.

Custom update interval

updateInterval controls how often the string re-renders — shorten it for a live-feeling "seconds ago" counter.

Falling back to a full date

max caps how far back the relative format goes; beyond it, fullDateFormatter renders an absolute date instead.

Showing seconds

By default, anything under a minute collapses to "just now". showSecond keeps the seconds unit instead.

Custom messages

Supply your own TimeAgoMessages table to fully control the wording for every unit.

RTL

The default Persian message table already reads correctly right-to-left; there's no bidi-specific fix needed here beyond using it inside Persian content, as shown below.

API Reference

useTimeAgo(time, options?)

Prop	Type	Default	Description
time	Date \| number \| string	—	The moment to compare against now.
updateInterval	number	30000	Re-render interval in milliseconds. Set 0 to compute once and never update.
max	TimeAgoUnitName \| number	undefined	Beyond this many milliseconds (or this unit's max), fall back to a full date.
fullDateFormatter	(date: Date) => string	formatDate(date, "yyyy/MM/dd")	Formatter used for the full-date fallback.
messages	TimeAgoMessages	faMessages	Message table used to render each unit. See faMessages/enMessages below.
locale	"fa" \| "en"	"fa"	Selects faMessages or enMessages when messages isn't given explicitly.
calendarType	"shamsi" \| "miladi"	"shamsi"	Calendar used by the default fullDateFormatter.
showSecond	boolean	false	Show seconds instead of collapsing sub-minute diffs into "just now".
rounding	"round" \| "ceil" \| "floor" \| number	"round"	Rounding strategy for each unit's numeric value, or a fixed decimal precision.
units	TimeAgoUnit[]	DEFAULT_UNITS	Override the unit table (thresholds in milliseconds).

formatTimeAgo

Prop	Type	Default	Description
formatTimeAgo(from, options?, now?)	(from: Date, options?: FormatTimeAgoOptions, now?: Date \| number) => string	—	Pure function counterpart of useTimeAgo — formats the difference between from and now as a relative time string. Accepts the same options minus updateInterval.

TimeAgoMessages

Prop	Type	Default	Description
justNow	string	—	Shown for diffs under a minute, unless showSecond is set.
past / future	string \| (value: string, isPast: boolean) => string	—	Wraps the formatted unit string, e.g. "{0} ago" / "in {0}".
invalid	string	—	Fallback string when no unit matches (should not normally occur).
second / minute / hour / day / week / month / year	string \| (value: number, isPast: boolean) => string	—	Per-unit formatter. day/week/month/year formatters also receive isPast so they can special-case a value of 1 ("yesterday"/"tomorrow").

Built-in message tables

Prop	Type	Default	Description
faMessages	TimeAgoMessages	—	Built-in Persian message table, the default when locale isn't "en".
enMessages	TimeAgoMessages	—	Built-in English message table, used when locale is "en".

Edit this page on GitHub

PrevioususeMediaQuery