Time Ago

A hydration-safe time element that turns an absolute date into a compact relative label.

Use Time Ago for recent activity, comments, status changes, and scheduled events where the distance from now matters more than the calendar date.

Status updated…Comment added…Build completed…Project created…

Recent activity

Installation

$npx shadcn@latest add @patchui/time-ago

The copied source is available in the registry JSON. The canonical implementation lives in packages/react/src/components/time-ago.tsx.

Usage

<TimeAgo dateStr={activity.createdAt} />

Pass an ISO date string. The component renders an absolute UTC date during server rendering, then replaces it with relative time after hydration.

Examples

Future time

Future dates use the same scale and render labels such as Soon, in 5m, or in 3h.

Maintenance starts …

Scheduled event

API reference

Prop	Type	Default	Description
dateStr	string	-	Sets the past or future ISO date represented by the time element.
fallback	string	absolute UTC date	Overrides the stable label rendered before hydration.
variant	"mono" \| "sans"	"mono"	Uses tabular numerals or inherits the surrounding typography.
liveUpdate	boolean	true	Keeps recent labels current using age-based refresh intervals.

Labels progress from seconds through minutes, hours, days, weeks, months, and years. Set liveUpdate={false} for large archives where automatic refreshes are unnecessary.

Accessibility

The rendered time element retains the complete ISO value in dateTime.
Keep enough surrounding text for a relative label to make sense on its own.
Add a Tooltip with the localized absolute date when exact time is important.
Do not rely on relative time alone for deadlines or other high-consequence dates.