native-time-ago

A tiny, zero-dependency utility that converts JavaScript Dates into human-readable strings like "3 hours ago" or "in 2 days" using native browser APIs.

Why? • Install • Usage • Locales

Why?

The native Intl.RelativeTimeFormat API is powerful, but it's "dumb"—it doesn't calculate time differences. If you want "3 hours ago," you have to manually calculate how many seconds have passed, divide by 3600 to get hours, and then pass exactly (-3, "hours") to the native formatter.

This package handles the math. It takes a date, calculates the optimal unit (seconds → minutes → hours → days → weeks → months → years), and passes the correct number and unit to the native formatter.

Features

• Zero Dependencies - Only ~1388 bytes
• 100+ Languages - Supports any locale via Intl.RelativeTimeFormat
• Framework Agnostic - Works in React, Vue, Svelte, Angular, Node.js, Bun
• Auto-updating - Translations improve as browsers update

Install

npm install native-time-ago

Usage

import timeAgo from 'native-time-ago';

// Basic usage
timeAgo(new Date(Date.now() - 3 * 60 * 60 * 1000));  // "3 hours ago"
timeAgo(new Date('2026-03-03T12:00:00Z'));            // "3 hours ago"

// Future dates
timeAgo(new Date(Date.now() + 2 * 24 * 60 * 60 * 1000));  // "in 2 days"

// Different locales
timeAgo(new Date(Date.now() - 3 * 60 * 60 * 1000), 'es');  // "hace 3 horas"
timeAgo(new Date(Date.now() - 3 * 60 * 60 * 1000), 'ja');  // "3 時間前"
timeAgo(new Date(Date.now() - 3 * 60 * 60 * 1000), 'fr');  // "il y a 3 heures"

// Pass string or number
timeAgo('2026-03-03T12:00:00Z', 'en');
timeAgo(1709476800000, 'en');

Comparison

// OLD WAY (heavy, many dependencies)
import { formatDistanceToNow } from 'date-fns';
import { es } from 'date-fns/locale';
formatDistanceToNow(new Date(2026, 2, 3), { locale: es, addSuffix: true });

// NEW WAY (zero dependencies)
import timeAgo from 'native-time-ago';
timeAgo(new Date('2026-03-03T12:00:00Z'), 'es');

Supported Locales

Any locale supported by Intl.RelativeTimeFormat:

• en, es, fr, de, it, pt, ru, ja, ko, zh, ar, and 100+ more

API

timeAgo(date, locale?)

• date - Date | string | number - The date to format
• locale - string - Optional locale code (default: 'en')

Returns a string like "3 hours ago", "in 2 days", or "now".

License

MIT