Skip to content

Relative Time

The time since or until a moment, kept current, with the exact time in a tooltip.

StatusCreatedReady
by tonyTS

Installation

  1. Add the registryOnce per project
  2. Add relative-time

Usage

date takes a Date, a timestamp in milliseconds or a string Date can parse, such as an ISO date. The component renders a <time> element whose dateTime is the date in ISO format, and updates its text as time passes.

Within 45 seconds either way, it reads now, which also covers small differences between the server's clock and the browser's. Beyond that, it rounds to the nearest minute, then hour, day, month and year, so 1 hour and 56 minutes reads 2h ago. Times in the future read in 5m.

Hovering, focusing or tapping the time opens a Tooltip that shows how long ago it was in its three largest units, such as 2 years, 3 months, 5 days or 1 hour, 56 minutes, 29 seconds, and the date and time in UTC and in the viewer's own time zone. Screen readers read the time written out in full, such as 2 hours ago, followed by the date and time in the viewer's own time zone, or in the first of timeZones when it doesn't list local.

Server rendering

The current time differs between the server and the browser, so on the server the component renders the date instead, in UTC, such as Oct 14, 2026. Once the page hydrates, the date is replaced with the time relative to the browser's clock. Users without JavaScript see the date, and a page prerendered at build time never shows how long ago it was built.

A page that the server renders on each request can show the relative time from the start. Pass the time the page rendered at to RelativeTimeProvider as initialNow, and send it to the browser with the page's data, so the server render and hydration describe each date relative to the same moment. After hydration, the times follow the browser's clock.

src/routes/deployments.tsx

Leave initialNow out of prerendered pages, where it would be the time of the build. The provider can also set locale and timeZones for every time inside it.

The time zones show only in the tooltip, which the server never renders, so they always match the viewer's. All the times on a page share one timer, which fires only when a time's text is due to change and stops while the tab is hidden.

formatRelativeTime(date, now?, { locale?, format? }) returns the same text as a string, for places a component can't go, such as a Toast's title or the page's title. The file is a client module, so call the function from client code. A server component, as in Next.js, receives a client reference rather than the function itself.

Composition

Examples

Formats

format sets how much the units are abbreviated.

Time zones

timeZones lists the tooltip's time zones by their IANA names, with local for the viewer's own.

Incident opened

Fixed reference

now fixes the moment each date is relative to, so the text doesn't change. Use it for screenshots, tests and times measured from a moment other than the present.

Certificate renews
Maintenance window
Backup finished
Last deploy
Project created

Labels

locale sets how the time is formatted, and labels replaces the tooltip's words. Pass only the labels you want to change.

Without a tooltip

Set tooltip to false where the exact time isn't needed, such as in a long list. With a tooltip, each time is a stop for the Tab key, so keyboard users can open it, which adds up in a table with a time on every row.

Updated

Props

Base UI's styling (opens in a new tab) and composition (opens in a new tab) guides say more about className, style and render.

RelativeTime

RelativeTimeProvider

RelativeTimeLabels

labels takes any of these, and keeps the English default for the rest.