@date-js/dom-timeago

One attribute. Live, human-readable dates. Zero boilerplate.

<span data-timeago="1579950627">26/01/2020</span>
<!-- becomes → "2 minutes ago", then "Today at 12:10", then "Yesterday at 12:10"… automatically -->

→ Live demo

---

Why @date-js/dom-timeago?

Most relative-date libraries give you a formatting function. You call it once, you get a string, and you're on your own: looping over elements, setting up timers, deciding when to re-render.

@date-js/dom-timeago works differently. Put a timestamp in an attribute, call DomTimeago.start() once, and every date on the page stays current on its own.

What sets it apart:

• HTML-first: no JS per element. One attribute, one start() call, done
• Smart per-item scheduling: each rule sets its own refresh interval. "30 seconds ago" re-evaluates on the next tick; "March 12" never re-evaluates. Items that no longer need updates are dropped from tracking entirely
• Rule-based rendering: the display logic is a plain list of conditions you fully control. Override a default, add your own, or replace them all
• Auto-discovery: dynamically added elements are picked up automatically via MutationObserver, works seamlessly in SPAs
• Tiny: ~3 KB gzipped
• Multilingual: extensible to any locale by adding a key in each rule's text

---

Install & Usage

npm / bundler

npm install @date-js/dom-timeago

import DomTimeago from '@date-js/dom-timeago';
DomTimeago.start();

<script> tag, UMD (CDN)

No build step. DomTimeago is available as a global.

<script src="https://cdn.jsdelivr.net/npm/@date-js/dom-timeago@3/dist/dom-timeago.umd.js"></script>
<script>
  DomTimeago.start();
</script>

<script type="module">, ESM (CDN)

<script type="module">
  import DomTimeago from 'https://cdn.jsdelivr.net/npm/@date-js/dom-timeago@3/dist/dom-timeago.esm.js';
  DomTimeago.start();
</script>

---

In all cases, the original content is preserved as a title attribute, and the element updates live:

<span title="26/01/2020 12h10">2 minutes ago</span>

Stop it anytime:

DomTimeago.stop();

Configuration

DomTimeago.start({
  refresh: 5,            // global re-render interval in seconds (default: 5)
  selector: 'data-timeago', // attribute to look for (default: 'data-timeago')
  rules: [],             // custom rules, evaluated before defaults
});

Custom rules

Rules are evaluated in order; the first matching one wins. Each rule defines when it applies, what to display, and how often to refresh.

DomTimeago.start({
// or DomTimeago.start({
  rules: [
    {
      condition: (interval) => interval.day >= 365 * 10,
      refresh: null, // never re-renders
      text: {
        en: "%dd day{%dd||s} ago (year %Y)",
        fr: "il y a %dd jour{%dd||s} (année %Y)",
      }
    }
  ]
});

Custom rules are evaluated before the defaults; the first matching rule wins.

See all default rules in src/defaultRules.ts and the DateInterval shape in src/DateInterval/DateInterval.ts.

Rule properties

Property	Type	Description
condition	(interval: DateInterval) => boolean	Returns true if this rule applies. interval contains day, hour, minute, second (elapsed) and date (original Date)
text	Record<string, string>	Locale-keyed display templates. A rule is skipped if the current locale key is missing
refresh	number | null | undefined	Seconds until next render (null = never, undefined = global interval)

Template tokens

Interval tokens (elapsed time): %ds seconds · %dm minutes · %dh hours · %dd days

Date tokens (formatted via @date-js/date-formatter): %H hour · %i minutes · %d day · %j day (no leading zero) · %F month name · %Y year · %l weekday

Pluralization: {%dd|singular|plural}

Languages

Detected automatically from navigator.language.

To add a language, include a key in each rule's text object matching the locale code (e.g. "de", "es").