Relative time | Glaze design system

Format

When to use it

Use: When something happened matters more than the exact clock: activity, last edited, last used.
Use: A column of times that must stay narrow and line up.
Not for: A schedule or a deadline someone plans around; write the date and time. Use Data list.
Not for: A duration such as 2m 14s; write it with tabular figures.

6 rules

Never: Format "x minutes ago" by hand or with a timer of your own. Because a hand timer re-renders every row on a fixed beat and still lags the boundary, and the server and the browser disagree on the first render.
Must: Pass the moment as a Date, an ISO string or epoch milliseconds, never a preformatted string. Because RelativeTime needs the instant to tick, to write the dateTime attribute and to show local time and UTC in the hint.
Should: Use the short format in rows and columns and format="long" inside a sentence. Because "3m ago" keeps a column narrow, and "3 minutes ago" reads as words in a line of text.
Must: Pass now in tests, docs and screenshots. Because a live clock makes every snapshot differ, and now freezes the label and stops the ticking.
Never: Set a time in text-text-3; it is read, so it takes text-2 or text-1. Because text-3 is 3.3:1, for placeholders and icons, and a time is a value someone reads.
Should: Set hint={false} on times inside a row that is itself a link. Because each hinted time is a tab stop, and a row link with a time inside gives the row two.

3 checks

: A time element with a machine dateTime; a screen reader hears the long form and the exact local time.
: The hint opens on focus as well as hover; Escape closes it.
: The figures are tabular, so a column of times does not jitter as it ticks.

2 keys

6 edge cases

Under 45 seconds: Reads now.
Past a week: Turns into a date, with the year only when it differs.
Server render: Shows the UTC date until mounted, so the server and the browser agree.
Tab hidden: Stops ticking and catches up when shown.
Invalid date: Reads "Unknown time" in text-2.
200 times on a page: Each ticks only at its own next boundary.

4 props

5 tokens