Relative Time

Formats JavaScript dates to localized relative time strings (e.g., "3 hours ago", "yesterday", "in 2 weeks").
It selects a best‑fit unit for you (seconds → minutes → hours → days → weeks → months → years) and uses the platform’s Intl.RelativeTimeFormat for localization.

- High‑level: RelativeTime → _resolve unit_ → format
- Low‑level: RelativeTimeResolver → _resolve only_ the { value, unit }

Built on Temporal for precise date math and Intl.RelativeTimeFormat for i18n. That means you get the same CLDR data your runtime ships with—no locale bundles to download.

> Why not just Intl.RelativeTimeFormat?
> Intl.RelativeTimeFormat is intentionally low level: you must choose the unit yourself (e.g., day vs week) and then ask it to format the pair {value, unit}. This library adds the unit resolver layer on top—by design that’s out of scope for the built‑in API. (see more details at tc39/proposal-intl-relative-time#14)

Install

``bash npm install relative-time`

`$3`

This library expects Temporal. Use it where Temporal is available, or load the official polyfill:

`bash npm install @js-temporal/polyfill`

When using @js-temporal/polyfill, inject Temporal when constructing RelativeTime/RelativeTimeResolver:

`js import RelativeTime, { RelativeTimeResolver } from "relative-time"; import { Temporal } from "@js-temporal/polyfill";

const rt = new RelativeTime({ Temporal }); // or: const resolver = new RelativeTimeResolver({ Temporal });`

`Quick start`

`js import RelativeTime from "relative-time"; // If needed: // import { Temporal } from "@js-temporal/polyfill";

const rt = new RelativeTime(); // locale inferred from the runtime

const threeHoursAgo = Temporal.Now.plainDateTimeISO().subtract({ hours: 3 }); rt.format(threeHoursAgo); // Output: "3 hours ago"

const pt = new RelativeTime("pt"); const oneHourAgo = Temporal.Now.plainDateTimeISO().subtract({ hours: 1 }); pt.format(oneHourAgo); // Output: "há 1 hora"`

`$3`

`js const rt = new RelativeTime();

const laDate = Temporal.ZonedDateTime.from( "2016-04-09T17:00:00-07:00[America/Los_Angeles]" ); rt.format(laDate); // Output: "yesterday" // Assuming now is "2016-04-10T05:00:00-07:00[America/Los_Angeles]"

const berlinDate = Temporal.ZonedDateTime.from( "2016-04-10T02:00:00+02:00[Europe/Berlin]" ); rt.format(berlinDate, { now: berlinNow }); // Output: "12 hours ago" // Assuming now is "2016-04-10T14:00:00+02:00[Europe/Berlin]"`

Use Temporal.PlainDateTime when you want to ignore time‑zone rules (local calendar math), and Temporal.ZonedDateTime when offset and DST must be respected.

`$3`

Use the resolver when you need just the unit/value.

`js import { RelativeTimeResolver } from "relative-time";

const resolver = new RelativeTimeResolver(); const event = Temporal.Now.plainDateTimeISO().subtract({ minutes: 3 }); const { value, unit } = resolver.resolve(event); // Output: { value: -3, unit: "minute" }

// You can format this yourself or with Intl.RelativeTimeFormat new Intl.RelativeTimeFormat(undefined, { numeric: "auto" }).format(value, unit); // Output: "3 minutes ago"`

`API`

`$3`

High‑level formatter that resolves the unit and formats the string.

#### Constructor

`ts new RelativeTime( locales?: string | string[], options?: Intl.RelativeTimeFormatOptions )`

- locales — same semantics as other Intl constructors (e.g., "en", ["fr", "en"]). -options — forwarded to Intl.RelativeTimeFormat (e.g., { style: "short", numeric: "auto" }). Tip:numeric: "auto" yields strings like “yesterday/tomorrow”; numeric: "always" gives “1 day ago / in 1 day”.

#### format(date, options?) => string

`ts format( date: Temporal.PlainDateTime | Temporal.ZonedDateTime, options?: { now?: Temporal.PlainDateTime | Temporal.ZonedDateTime, unit?: "best-fit" | "second" | "minute" | "hour" | "day" | "week" | "month" | "year" } ): string`

- date— the target moment. -options.now — reference moment (defaults to “now”, matched to date’s type). -options.unit — force a specific unit or let the library decide with "best-fit" (default).

How “best‑fit” works (conceptually)

The resolver promotes units using _calendar boundaries_ and _configurable step-up thresholds_ (e.g., sec → min → hr → day → month). If the difference crosses a calendar day, you'll get _"yesterday"_ (instead of "20 hours ago"). But if it crosses midnight _without_ clearing the threshold, it stays in hours, e.g., _"3 hours ago"_ (instead of "yesterday").

---

`$3`

Low‑level unit chooser. Use it if you want the { value, unit } pair to feed into your own formatter (including Intl.RelativeTimeFormat directly).

#### Constructor

`ts new RelativeTimeResolver();`

#### resolve(date, options?) => { value: number, unit: RTFUnit }

resolve( date: Temporal.PlainDateTime | Temporal.ZonedDateTime, options?: { now?: Temporal.PlainDateTime | Temporal.ZonedDateTime, unit?: "best-fit" | RTFUnit // "best-fit" (default) or force a unit } ): { value: number; unit: RTFUnit }`

Example

`js import { RelativeTimeResolver } from "relative-time";

const r = new RelativeTimeResolver(); const target = Temporal.Now.plainDateTimeISO().add({ days: 6, hours: 5 });

const { value, unit } = r.resolve(target); // e.g., { value: 1, unit: "week" }

new Intl.RelativeTimeFormat("en", { numeric: "auto" }).format(value, unit); // "next week"`

`Using` Intl.RelativeTimeFormat `options`

You can customize style and numeric behavior at construction:

`js const rtShort = new RelativeTime("en", { style: "short", numeric: "always" }); rtShort.format(Temporal.Now.plainDateTimeISO().subtract({ day: 1 })); // "1 day ago"`

> RelativeTime is literally a thin wrapper over Intl.RelativeTimeFormat once a { value, unit } has been resolved. You get the same pluralization and grammar your engine provides.

`When to use which`

| You need… | Use | Why | | --------------------------------- | ---------------------------------- | ------------------------------------------------------------- | | “Just give me a localized string” |RelativeTime| Picks a sensible unit and formats it | |{ value, unit } only | RelativeTimeResolver| Feed another formatter, build custom UIs, analytics, etc. | | Full control over unit and i18n |Intl.RelativeTimeFormat directly | Low‑level by design; no unit resolution provided by the spec. |

`Examples`

Force a unit

`js const rt = new RelativeTime("en"); rt.format(Temporal.Now.plainDateTimeISO().subtract({ hours: 27 }), { unit: "hour", }); // "27 hours ago"`

Different locales

`js new RelativeTime(["fr", "en"]).format( Temporal.Now.plainDateTimeISO().add({ minutes: 5 }) ); // "dans 5 minutes"`

`Notes on accuracy`

This project uses Temporal for differences (calendar‑aware) and Intl.RelativeTimeFormat for localization. That combination prevents common errors around DST, month lengths, and week boundaries that “approximate threshold” libraries can exhibit.

`Browser / runtime support`

- Works wherever Temporal is available; otherwise include @js-temporal/polyfill. - Uses your runtime’sIntl.RelativeTimeFormat, which has wide support in modern environments.

`FAQ`

Does this support quarters? No—units are:second, minute, hour, day, week, month, year.

Why do I sometimes see “yesterday” instead of “1 day ago”? That comes fromnumeric: "auto" in Intl.RelativeTimeFormat. Switch to numeric: "always" if you prefer numbers only.

How is this different from the TC39 proposal? This library’s resolver is the high‑level part omitted on purpose from theIntl.RelativeTimeFormat spec; the built‑in API only formats a supplied { value, unit }. See the historical discussion around “best‑fit” in the proposal repo.

`Contributing`

PRs and issues welcome!

`Appendix`

`$3`

In this library, we'll define relative time as what makes sense for expressions like "now", "2 days ago", "in 3 months", "last year", "yesterday", and so on. In a more formal definition, _relative time_ is an approximate date distance given a unit. This is, _relative time_ is the date distance of _a_ and _b_ ± error, where error < unit. Please, see the below examples of each unit for clarity.

#### second

`8:31:38.000 8:31:39.000 8:31:40.000 8:31:41.000 ms | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | sec | e d | c b | a N | 8:31:38 8:31:39 8:31:40 8:31:41

N: The assumed now a: now / 0 seconds ago b: 1 second ago c: 1 second ago d: 2 seconds ago e: 2 seconds ago`

#### minute

`8:28:00 8:29:00 8:30:00 8:31:00 8:32:00 sec | | | | | | | | | | | | | | | | | | | | | | | | | | | min | g f | e d | c b | a N | 8:28 8:29 8:30 8:31 8:32

N: The assumed now a: 0 minutes ago b: 1 minute ago c: 1 minute ago d: 2 minutes ago e: 2 minutes ago f: 3 minutes ago g: 3 minutes ago`

#### hour

`5:00 6:00 7:00 8:00 9:00 min | | | | | | | | | | | | | | | | | | | | | | | | | | | hr. | g f | e d | c b | a N | 5 6 7 8 9

N: The assumed now a: 0 hours ago b: 1 hour ago c: 1 hour ago d: 2 hours ago e: 2 hours ago f: 3 hours ago g: 3 hours ago`

#### day

`Mar 21, 00:00 Mar 22, 00:00 Mar 23, 00:00 Mar 24, 00:00 hr. | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | day | e d | c b | a N | Mar 21 Mar 22 Mar 23 Mar 24

N: The assumed now a: today / 0 days ago b: yesterday / 1 day ago c: yesterday / 1 day ago d: 2 days ago e: 2 days ago`

#### week

N: The assumed now a: this week b: last week c: last week d: 2 weeks ago e: 2 weeks ago`

#### month

`Wk. 1 Wk. 5 Wk. 9 Wk. 14 wk. | | | | | | | | | | | | | | mo. |e d | c b| a N | Jan Feb Mar Apr

N: The assumed now a: this month / 0 months ago b: last month / 1 month ago c: last month / 1 month ago d: 2 months ago e: 2 months ago`

Note the months distances doesn't match weeks distance or days distance uniformly.

#### year

`Jan Jan Jan Jan Jan mo. | | | | | | | | | | | | | | | | | | | | | | | | | | | yr. |g f |e d |c b |a N | 2013 2014 2015 2016 2017

N: The assumed now a: this year / 0 years ago b: last year / 1 year ago c: last year / 1 year ago d: 2 years ago e: 2 years ago f: 3 years ago g: 3 years ago``

Note that (although not shown by the above ruler), the years distances doesn't match weeks distance or days distance uniformly.

License

MIT © Rafael Xavier de Souza

Relative Time

- High‑level: RelativeTime → _resolve unit_ → format
- Low‑level: RelativeTimeResolver → _resolve only_ the { value, unit }

Built on Temporal for precise date math and Intl.RelativeTimeFormat for i18n. That means you get the same CLDR data your runtime ships with—no locale bundles to download.

Install

``bash npm install relative-time`

`$3`

This library expects Temporal. Use it where Temporal is available, or load the official polyfill:

`bash npm install @js-temporal/polyfill`

When using @js-temporal/polyfill, inject Temporal when constructing RelativeTime/RelativeTimeResolver:

`js import RelativeTime, { RelativeTimeResolver } from "relative-time"; import { Temporal } from "@js-temporal/polyfill";

const rt = new RelativeTime({ Temporal }); // or: const resolver = new RelativeTimeResolver({ Temporal });`

`Quick start`

`js import RelativeTime from "relative-time"; // If needed: // import { Temporal } from "@js-temporal/polyfill";

const rt = new RelativeTime(); // locale inferred from the runtime

const threeHoursAgo = Temporal.Now.plainDateTimeISO().subtract({ hours: 3 }); rt.format(threeHoursAgo); // Output: "3 hours ago"

const pt = new RelativeTime("pt"); const oneHourAgo = Temporal.Now.plainDateTimeISO().subtract({ hours: 1 }); pt.format(oneHourAgo); // Output: "há 1 hora"`

`$3`

`js const rt = new RelativeTime();

Use Temporal.PlainDateTime when you want to ignore time‑zone rules (local calendar math), and Temporal.ZonedDateTime when offset and DST must be respected.

`$3`

Use the resolver when you need just the unit/value.

`js import { RelativeTimeResolver } from "relative-time";

// You can format this yourself or with Intl.RelativeTimeFormat new Intl.RelativeTimeFormat(undefined, { numeric: "auto" }).format(value, unit); // Output: "3 minutes ago"`

`API`

`$3`

High‑level formatter that resolves the unit and formats the string.

#### Constructor

`ts new RelativeTime( locales?: string | string[], options?: Intl.RelativeTimeFormatOptions )`

#### format(date, options?) => string

How “best‑fit” works (conceptually)

---

`$3`

Low‑level unit chooser. Use it if you want the { value, unit } pair to feed into your own formatter (including Intl.RelativeTimeFormat directly).

#### Constructor

`ts new RelativeTimeResolver();`

#### resolve(date, options?) => { value: number, unit: RTFUnit }

Example

`js import { RelativeTimeResolver } from "relative-time";

const r = new RelativeTimeResolver(); const target = Temporal.Now.plainDateTimeISO().add({ days: 6, hours: 5 });

const { value, unit } = r.resolve(target); // e.g., { value: 1, unit: "week" }

new Intl.RelativeTimeFormat("en", { numeric: "auto" }).format(value, unit); // "next week"`

`Using` Intl.RelativeTimeFormat `options`

You can customize style and numeric behavior at construction:

`js const rtShort = new RelativeTime("en", { style: "short", numeric: "always" }); rtShort.format(Temporal.Now.plainDateTimeISO().subtract({ day: 1 })); // "1 day ago"`

> RelativeTime is literally a thin wrapper over Intl.RelativeTimeFormat once a { value, unit } has been resolved. You get the same pluralization and grammar your engine provides.

`When to use which`

`Examples`

Force a unit

`js const rt = new RelativeTime("en"); rt.format(Temporal.Now.plainDateTimeISO().subtract({ hours: 27 }), { unit: "hour", }); // "27 hours ago"`

Different locales

`js new RelativeTime(["fr", "en"]).format( Temporal.Now.plainDateTimeISO().add({ minutes: 5 }) ); // "dans 5 minutes"`

`Notes on accuracy`

`Browser / runtime support`

- Works wherever Temporal is available; otherwise include @js-temporal/polyfill. - Uses your runtime’sIntl.RelativeTimeFormat, which has wide support in modern environments.

`FAQ`

Does this support quarters? No—units are:second, minute, hour, day, week, month, year.

Why do I sometimes see “yesterday” instead of “1 day ago”? That comes fromnumeric: "auto" in Intl.RelativeTimeFormat. Switch to numeric: "always" if you prefer numbers only.

`Contributing`

PRs and issues welcome!

`Appendix`

`$3`

#### second

`8:31:38.000 8:31:39.000 8:31:40.000 8:31:41.000 ms | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | sec | e d | c b | a N | 8:31:38 8:31:39 8:31:40 8:31:41

N: The assumed now a: now / 0 seconds ago b: 1 second ago c: 1 second ago d: 2 seconds ago e: 2 seconds ago`

#### minute

`8:28:00 8:29:00 8:30:00 8:31:00 8:32:00 sec | | | | | | | | | | | | | | | | | | | | | | | | | | | min | g f | e d | c b | a N | 8:28 8:29 8:30 8:31 8:32

N: The assumed now a: 0 minutes ago b: 1 minute ago c: 1 minute ago d: 2 minutes ago e: 2 minutes ago f: 3 minutes ago g: 3 minutes ago`

#### hour

`5:00 6:00 7:00 8:00 9:00 min | | | | | | | | | | | | | | | | | | | | | | | | | | | hr. | g f | e d | c b | a N | 5 6 7 8 9

N: The assumed now a: 0 hours ago b: 1 hour ago c: 1 hour ago d: 2 hours ago e: 2 hours ago f: 3 hours ago g: 3 hours ago`

#### day

`Mar 21, 00:00 Mar 22, 00:00 Mar 23, 00:00 Mar 24, 00:00 hr. | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | day | e d | c b | a N | Mar 21 Mar 22 Mar 23 Mar 24

N: The assumed now a: today / 0 days ago b: yesterday / 1 day ago c: yesterday / 1 day ago d: 2 days ago e: 2 days ago`

#### week

N: The assumed now a: this week b: last week c: last week d: 2 weeks ago e: 2 weeks ago`

#### month

`Wk. 1 Wk. 5 Wk. 9 Wk. 14 wk. | | | | | | | | | | | | | | mo. |e d | c b| a N | Jan Feb Mar Apr

N: The assumed now a: this month / 0 months ago b: last month / 1 month ago c: last month / 1 month ago d: 2 months ago e: 2 months ago`

Note the months distances doesn't match weeks distance or days distance uniformly.

#### year

`Jan Jan Jan Jan Jan mo. | | | | | | | | | | | | | | | | | | | | | | | | | | | yr. |g f |e d |c b |a N | 2013 2014 2015 2016 2017

N: The assumed now a: this year / 0 years ago b: last year / 1 year ago c: last year / 1 year ago d: 2 years ago e: 2 years ago f: 3 years ago g: 3 years ago``

Note that (although not shown by the above ruler), the years distances doesn't match weeks distance or days distance uniformly.

relative-time

Relative Time

Install

$3

Quick start

$3

$3

API

$3

$3

Using Intl.RelativeTimeFormat options

When to use which

Examples

Notes on accuracy

Browser / runtime support

FAQ

Contributing

Appendix

$3

License

relative-time

Relative Time

Install

$3

Quick start

$3

$3

API

$3

$3

Using Intl.RelativeTimeFormat options

When to use which

Examples

Notes on accuracy

Browser / runtime support

FAQ

Contributing

Appendix

$3

License

`$3`

`Quick start`

`$3`

`$3`

`API`

`$3`

`$3`

`Using` Intl.RelativeTimeFormat `options`

`When to use which`

`Examples`

`Notes on accuracy`

`Browser / runtime support`

`FAQ`

`Contributing`

`Appendix`

`$3`

`$3`

`Quick start`

`$3`

`$3`

`API`

`$3`

`$3`

`Using` Intl.RelativeTimeFormat `options`

`When to use which`

`Examples`

`Notes on accuracy`

`Browser / runtime support`

`FAQ`

`Contributing`

`Appendix`

`$3`