Relative Time Calculator

Relative time formatting — the "3 days ago" pattern that ships in every modern UI

Every successful product UI shows times relatively rather than absolutely. GitHub commits, Slack messages, Twitter posts, Stripe transactions, Linear issues — they all tell you "5 minutes ago" or "yesterday" rather than dumping a full ISO timestamp. Relative formatting feels human; absolute formatting feels like log output. This guide covers the threshold buckets that produce natural-sounding phrases, the Intl.RelativeTimeFormat API that ships in every modern browser, the i18n surprises (English uses "yesterday"; Japanese has separate "昨日(kinou)" for spoken vs written), and the live-update pattern that keeps "1 minute ago" from going stale.

The threshold buckets — where the boundaries are

The convention used by Twitter, GitHub, Slack, and the JavaScript Intl spec all converge on roughly these thresholds:

Intl.RelativeTimeFormat — the platform API

The browser ships an i18n-aware relative-time formatter as of 2018 (Chrome 71, Firefox 65, Safari 14). It handles plurals, future vs past, and locale-specific phrasing automatically:

const rtf = new Intl.RelativeTimeFormat('en', { numeric: 'auto' });
rtf.format(-1, 'day');     // "yesterday"
rtf.format( 0, 'day');     // "today"
rtf.format( 1, 'day');     // "tomorrow"
rtf.format(-3, 'day');     // "3 days ago"
rtf.format( 5, 'minute');  // "in 5 minutes"

// numeric: 'always' forces numbers (for log displays)
new Intl.RelativeTimeFormat('en', { numeric: 'always' })
  .format(-1, 'day');      // "1 day ago"

// Different locales handle phrasing differently
new Intl.RelativeTimeFormat('ja', { numeric: 'auto' })
  .format(-1, 'day');      // "昨日"
new Intl.RelativeTimeFormat('de', { numeric: 'auto' })
  .format(-1, 'day');      // "gestern"

This is the recommended approach in 2026. It eliminates the "I shipped my homegrown relative formatter and it broke for German users" class of bug.

The live-update pattern — keeping "1 min ago" fresh

If the user lands on the page and a comment was posted 30 seconds ago, the UI shows "30 seconds ago". One minute later it should say "1 minute ago", then "2 minutes ago", and so on. The standard implementation:

function startRelativeTimeUpdates() {
  const elements = document.querySelectorAll('time[datetime]');

  function updateAll() {
    const now = Date.now();
    elements.forEach(el => {
      const t = new Date(el.dateTime).getTime();
      el.textContent = formatRelative(t - now);
    });
  }

  updateAll();
  setInterval(updateAll, 30_000);   // refresh every 30s
}

For a feed with hundreds of timestamps, batching updates like this beats a per-element timer. Stop the interval when the tab is hidden (use the Page Visibility API) to save battery.

Why "n minutes ago" vs "in n minutes" matters more than it seems

Future and past tense in relative time should never collide. A naive implementation might show:

• 30 seconds ago — the comment was posted just now (correct).
• 30 seconds ago — your access token expired 30 seconds ago (also correct, but the phrase is identical).
• in 30 seconds — your access token expires in 30 seconds (different).

Always preserve the sign of the delta. "Created 5 min ago" and "Expires in 5 min" are different states; collapsing them to the same phrase has caused real bugs in dashboard expiry warnings.

Time-zone surprises — the "yesterday" trap

"Yesterday" is a calendar concept, not a duration. A timestamp 18 hours ago might be "yesterday" or "today" depending on the user's local time:

• It is now 09:00 local. A timestamp 18 hours ago happened at 15:00 local yesterday. "Yesterday" is correct.
• It is now 23:00 local. A timestamp 18 hours ago happened at 05:00 local today. "Today" / "18 hours ago" is correct.

Use the local-date concept (zero-out the time portion of both timestamps and compare days) when you want to special-case "today", "yesterday", "last week".

Locale differences that bite

Languages with grammatical gender (Russian, Arabic) or different plural rules (Russian: 1 / 2-4 / 5+ all use different forms) make hand-rolling impossible. Always use Intl.RelativeTimeFormat for any product going beyond English.

Library landscape — when to reach for what

Common relative-time mistakes

• Forgetting to update. A static "5 minutes ago" rendered server-side becomes hilariously wrong an hour later. Always re-render or invalidate.
• Using "ago" for future timestamps. The expired/expires distinction must respect sign.
• Hand-rolling pluralization. "1 minutes ago" looks broken; "1 minute ago" requires plural-aware code. Intl handles this.
• Skipping the absolute timestamp on hover. "Yesterday" is friendly; for debugging or audit trails users need the actual timestamp. Render the absolute time in a title or <time datetime> attribute so it's accessible.
• Treating every event as relative. A meeting "in 3 hours" is helpful; a contract that "expires in 11 months" is not — show the actual date for far-future and far-past events.
• Forgetting screen readers. Wrap relative times in <time datetime="2026-05-02T14:30:00Z">3 hours ago</time> so assistive tech can announce the exact value if needed.
• Server / client clock drift. If your server thinks a comment was 0.1 s ago and the client thinks 30 s have passed, the relative phrase jumps. Use server-rendered relative time on initial load, then re-render on the client.