Time Ago Card

Overview

The TimeAgoCard component displays a timestamp in a human-readable format, such as “5 min. ago”. Hovering (or focusing) the value reveals a tooltip with the full date and time in both UTC and the local timezone.

Variations

Timestamp variants

The timestamp prop accepts an ISO 8601 string, a Unix timestamp number, or null. When omitted, nothing is rendered.

Time difference examples

The component displays relative time in a narrow format for all time ranges:

Future timestamps

The component also handles future timestamps:

With prefix

Live updating

Set live to have the relative time re-render every second so it stays current without a page refresh.

Installation

import { TimeAgoCard } from "@harnessio/ui/components";

<TimeAgoCard timestamp={new Date().toISOString()} />;

Usage

Anatomy

TimeAgoCard renders a trigger showing the relative time, with a tooltip that reveals the full date.

• The trigger is a <button> wrapping a Text rendered as a <time> element (with a dateTime attribute). It shows the relative time (prefixed with prefix when provided).
• On hover or focus, a tooltip opens showing the full date and time in two rows — UTC and the local timezone — each with a StatusBadge label.
• Relative time is formatted with the native Intl.RelativeTimeFormat in the narrow style, so output is abbreviated (e.g. “5 min. ago”, “2 days ago”, “in 1 yr.”) and localized to the user’s locale.

Invalid Date Handling

If an invalid date is passed to the timestamp prop (e.g. an invalid date string, NaN, or the Unix epoch 0), the component renders nothing visible and logs a warning to the browser console instead. Ensure the timestamp is a valid ISO 8601 string, a Unix timestamp number, or null.

Best practices

Do

• Use prefix to give the timestamp context (“Updated”, “Created”) when the surrounding text doesn’t already.
• Use live for timestamps a user watches in real time (e.g. a recently-triggered run), and leave it off for static lists to avoid unnecessary re-renders.
• Pass a valid ISO 8601 string or Unix timestamp so the value always renders.

Don’t

• Don’t rely on TimeAgoCard alone to convey a critical exact time — the precise value lives in the hover tooltip, which isn’t visible at a glance.
• Don’t pass a Date object; the prop expects a string, number, or null.

Accessibility

Keyboard

• The trigger is a real <button>, so it is focusable and the full-date tooltip opens on focus as well as hover.

Labeling & semantics

• The relative time is rendered inside a <time> element with a dateTime attribute, giving assistive tech and machines a precise, parseable value behind the human-readable text.

Properties

Properties

Prop	Required	Default	Type
timestamp	false		string | number | null
prefix	false		string
live	false	false	boolean
textProps	false		Omit<TextProps<'time' | 'span'>, 'ref'>
tooltipProps	false		TooltipProps
triggerProps	false		Omit<ButtonHTMLAttributes<HTMLButtonElement>, 'className'>
triggerClassName	false		string