- Add the registry
- 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.
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.
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.