@ramstack/timeago is a tiny utility that turns dates into live-updating relative time text like '3 minutes ago' or in '2 hours'.
npm install @ramstack/timeago@ramstack/timeago is a tiny utility that turns dates into live-updating relative time text like
"3 minutes ago" or "in 2 hours".
It automatically tracks elements with datetime or data-datetime, updates text only when needed
(using smart intervals), reacts to DOM changes, and cleans up after itself.
No polling every second. No manual updates.
The library is small enough - around 1.7 KB, or about 900 bytes gzipped.
Formatting is handled by the browser using Intl.RelativeTimeFormat, so the output follows
the browser's locale rules and language data.
bash
npm install @ramstack/timeago
`$3
html
`Quick start
Just call
and pass a selector.
It will find matching elements and start updating them.`html
`js
import { timeago } from "@ramstack/timeago";const cleanup = timeago("time");
`That's it. The text content will update automatically as time passes.
When you no longer need it:
js
cleanup();
`Using a custom locale
By default, the browser's locale is used. You can override it if needed:
js
timeago(".timeago", { locale: "es" });
`How it works (short version)
* Looks for elements matching your selector
* Reads date from
or data-datetime
* Updates text only when needed (smart intervals)
* Watches DOM changes using
* Cleans everything up when you call the returned functionNo polling every second. No manual updates.
API
$3
Starts tracking elements and returns a cleanup function.
#### Parameters
(required)
A CSS selector for elements that should display relative time.`js
timeago("[datetime]");
`
(optional)`ts
{
locale?: string;
}
`*
— locale code for formatting ("en", "fr", "ru", etc.)
* Defaults to the browser's locale#### Returns
A function that stops all updates and disconnects the observer.
`js
const cleanup = timeago(".timeago");// later
cleanup();
`Supported date formats
The date value can be:
* An ISO date string
html
`
* A unix timestamp in milliseconds
html
``If the date is invalid, the element is ignored.
https://github.com/rameel/ramstack.timeago.js/blob/main/src/timeago.ts