Displays a date as a localized phrase relative to now, such as “3 hours ago” or “in 2 days”. Localization is handled by Intl.RelativeTimeFormat.

Usage

Relative times display a date as a localized phrase relative to now, such as “3 hours ago” or “in 2 days”. The phrase is rendered with the browser’s Intl.RelativeTimeFormat API, so no language packs are required.

<orb-relative-time date="2025-12-02T00:00:00-05:00"></orb-relative-time>

Date

The date attribute sets the point in time the phrase is calculated from. If it’s not set, the current date and time is used.

It accepts any string that Date.parse() understands, or a Date object set via JavaScript.

Always use ISO 8601 date strings. Ambiguous formats like 03/04/2020 can be read as March 4 or April 3 depending on the user’s browser and locale. A valid ISO 8601 date-time string parses the same for every client.

HTML Javascript
<orb-relative-time id="date-demo"></orb-relative-time>
const relativeTime = document.querySelector("#date-demo");
relativeTime.setAttribute("date", new Date(Date.now() - 3 * 60 * 60 * 1000).toISOString());

Format

Use the format attribute to change how the phrase is written. Some locales display the same text for narrow and short.



<orb-relative-time date="2025-12-02T00:00:00-05:00" format="narrow"></orb-relative-time><br />
<orb-relative-time date="2025-12-02T00:00:00-05:00" format="short"></orb-relative-time><br />
<orb-relative-time date="2025-12-02T00:00:00-05:00" format="long"></orb-relative-time>

Numeric

By default, numeric="auto" uses phrases such as “yesterday” and “tomorrow” when they apply. Set numeric="always" to always show a number, such as “1 day ago” or “in 1 day”.


HTML Javascript
<orb-relative-time id="numeric-auto-demo"></orb-relative-time><br />
<orb-relative-time id="numeric-always-demo" numeric="always"></orb-relative-time>
const oneDayAgo = new Date(Date.now() - 24 * 60 * 60 * 1000).toISOString();
document.querySelector("#numeric-auto-demo").setAttribute("date", oneDayAgo);
document.querySelector("#numeric-always-demo").setAttribute("date", oneDayAgo);

Sync

Add the sync attribute to update the displayed phrase automatically as time passes.

HTML Javascript
<orb-relative-time id="sync-demo" sync></orb-relative-time>
const relativeTime = document.querySelector("#sync-demo");
relativeTime.setAttribute("date", new Date(Date.now() - 60000).toISOString());

Localization

The phrase uses the browser’s default locale. There is currently no way to choose a different locale on the component.

Properties

date

Description The date to calculate the time from. Defaults to the current date and time. Strings should be ISO 8601 so they parse the same in every browser.
Attribute date
Type Date | string
Default undefined

format

Description The formatting style to use.
Attribute format
Type "long" | "narrow" | "short"
Default "long"

numeric

Description When auto, values such as “yesterday” and “tomorrow” are shown when possible. When always, values such as “1 day ago” are shown.
Attribute numeric
Type "always" | "auto"
Default "auto"

sync

Description Keep the displayed value up to date as time passes.
Attribute sync
Type boolean
Default false