Tiny human-readable date formatter built on native Intl.
Turn dates into "now", "yesterday, 2:35 PM", "через 3 часа", or "2016年2月5日".
One function. Smart defaults. Any locale. ~1.3kb gzip. Zero dependencies.
Intl is powerful. anywhen makes it usable.
Built for feeds, chats, notifications, dashboards, and docs — anywhere a raw timestamp should read like a person wrote it. No locale files. No plugins. No config.
import { anywhen } from "anywhen";
anywhen(date);
// "yesterday, 2:35 PM" — smart mode (default)
anywhen(date, { mode: "absolute", locale: "en" });
// "Feb 5, 2016"
anywhen(date, { mode: "relative", locale: "en" });
// "3 hours ago"
anywhen(date, { mode: "relative", locale: "ru" });
// "3 часа назад"
anywhen(date, { mode: "absolute", locale: "ja" });
// "2016年2月5日"npm install anywhenanywhen(input);
anywhen(input, options);input is a Date, unix timestamp, or ISO string.
anywhen(new Date());
anywhen(Date.now());
anywhen("2016-02-05T14:00:00Z");Copy, paste, move on.
// Blog post date
<time dateTime={post.createdAt}>
{anywhen(post.createdAt, { locale: "en", time: false })}
</time>
// Chat message
<time dateTime={message.sentAt}>
{anywhen(message.sentAt, { locale: "en" })}
</time>
// Notification
anywhen(notification.createdAt, { mode: "relative", locale: "en" });
// "3 minutes ago"
// Settings screen / invoice date
anywhen(invoice.date, {
mode: "absolute",
locale: "en",
format: { month: "long", day: "numeric", year: "numeric" },
});
// "February 5, 2016"
// SSR-safe Next.js / React Server Components
anywhen(createdAt, {
locale: "en",
now: requestTime,
timeZone: "Europe/Belgrade",
});The mode option picks the rendering strategy. Default is "smart".
Context-aware. Picks the most readable format based on distance from now — covers past and future.
anywhen(date, { locale: "en" });
// < 45s → "now"
// < 1 hour → "10 minutes ago"
// future > 1 hour → "in 2 weeks"
// same day → "today, 14:35"
// yesterday → "yesterday, 09:00"
// < 7 days → "Wednesday, 11:20"
// older → "Feb 5, 2016"
anywhen(date, { locale: "en", time: false });
// "yesterday" — clock removed
anywhen(date, { locale: "en", now: requestTime, timeZone: "Europe/Belgrade" });
// SSR-safe with stable anchor + timezone
anywhen(date, { locale: "en", style: "short" });
// "10 min. ago" — shortens relative wording, calendar labels keep their clockReads: locale, now, time, timeZone, style, thresholds.
style maps to Intl.RelativeTimeFormat and only changes the relative
phrasing ("now", "10 min. ago", "in 3 hr."). Calendar labels
(today, yesterday, weekday) and the absolute fallback are unaffected.
By default, smart mode uses time: true, so nearby past dates stay useful in
feeds, chats, and activity logs: "today, 2:35 PM",
"yesterday, 09:00", "Wednesday, 11:20". Use time: false for compact UI
where the label is enough: "today", "yesterday", "Wednesday".
Plain date formatting via Intl.DateTimeFormat. Pass format to control the
output shape.
anywhen(date, { mode: "absolute", locale: "en" });
// "Feb 5, 2016"
anywhen(date, {
mode: "absolute",
locale: "en",
format: { hour: "2-digit", minute: "2-digit" },
});
// "2:35 PM"
anywhen(date, {
mode: "absolute",
locale: "en",
format: { weekday: "long", month: "long", day: "numeric", year: "numeric" },
});
// "Friday, February 5, 2016"Reads: locale, format, timeZone.
Always relative. Past and future. Never falls back to absolute.
anywhen(date, { mode: "relative", locale: "en" });
// "3 hours ago"
// "yesterday"
// "in 2 weeks"
anywhen(date, { mode: "relative", locale: "en", numeric: true });
// "1 day ago" — disables auto-phrases like "yesterday"
// "1 week ago"
anywhen(date, { mode: "relative", locale: "en", style: "short" });
// "3 hr. ago"
anywhen(date, { mode: "relative", locale: "en", style: "narrow" });
// "3h ago"Reads: locale, now, numeric, style, thresholds.
| Option | Type | Default | Used by |
|---|---|---|---|
mode |
"smart" | "absolute" | "relative" |
"smart" |
— |
locale |
string | string[] |
runtime locale | all |
now |
Date | number | string |
current time | smart, relative |
timeZone |
string |
runtime timezone | smart, absolute |
time |
boolean |
true |
smart |
numeric |
boolean |
false |
relative |
style |
"long" | "short" | "narrow" |
"long" |
smart, relative |
format |
Intl.DateTimeFormatOptions |
{ day, month, year } |
absolute |
thresholds |
Partial<Record<unit, number>> |
built-in table | smart, relative |
Each mode reads only the options that apply to it. The rest are ignored.
Each unit (second, minute, hour, day, week, month) is shown while
the distance from now is below its cutoff, in seconds. Override any subset —
the rest keep their defaults (second: 45, minute: 2700, hour: 79200,
day: 518400, week: 2160000, month: 28512000).
anywhen(date, { mode: "relative", locale: "en", thresholds: { minute: 5400 } });
// 50 minutes ago → "50 minutes ago" instead of "1 hour ago"
anywhen(date, { locale: "en", thresholds: { second: 120 } });
// smart mode: "now" covers the first 2 minutesIn smart mode thresholds.second widens the "now" window, and the full
table applies to future dates. Calendar labels (today, yesterday,
weekday) are not affected.
anywhenParts() accepts the same arguments as anywhen() and returns the
output as { type, value, unit? } parts — style the number apart from the
unit, or rebuild the string your own way.
import { anywhenParts } from "anywhen";
anywhenParts(date, { mode: "relative", locale: "en" });
// [
// { type: "integer", value: "3", unit: "hour" },
// { type: "literal", value: " hours ago" },
// ]
// React: bold the number
anywhenParts(date, { mode: "relative" }).map((p, i) =>
p.type === "integer" ? <b key={i}>{p.value}</b> : p.value,
);Wrap output in <time> so machines still get the exact timestamp.
import { anywhen } from "anywhen";
export function PostMeta({ createdAt }: { createdAt: string }) {
return <time dateTime={createdAt}>{anywhen(createdAt)}</time>;
}For SSR, pass now to keep server and client output stable across the
hydration boundary.
export function PostMeta({
createdAt,
requestTime,
}: {
createdAt: string;
requestTime: string;
}) {
return (
<time dateTime={createdAt}>
{anywhen(createdAt, {
locale: "en",
now: requestTime,
timeZone: "Europe/Belgrade",
})}
</time>
);
}now freezes the relative anchor. timeZone controls both the displayed
clock and the smart calendar boundaries (today, yesterday, weekday).
Pass any valid BCP 47 tag — including regional variants like en-GB, zh-TW,
pt-BR. Fallback arrays also work.
anywhen(date, { locale: "de" }); // "gestern, 14:35"
anywhen(date, { locale: "ru" }); // "вчера, 14:35"
anywhen(date, { locale: "fr" }); // "hier, 14:35"
anywhen(date, { locale: ["sr-Latn-RS", "en"] });
anywhen(date, { mode: "absolute", locale: "ja" }); // "2016年2月5日"
anywhen(date, { mode: "absolute", locale: "ar" }); // "٥ فبراير ٢٠١٦"
anywhen(date, { mode: "relative", locale: "tr" }); // "3 saat önce"When omitted, native Intl uses the runtime locale.
| anywhen | dayjs | date-fns | |
|---|---|---|---|
| gzip | ~1.3kb | ~7kb | ~20kb |
| locale data bundled | no | yes | yes |
| locales | 200+ | 140 | 100 |
| dependencies | 0 | 0 | 0 |
anywhen follows semver. Since 1.0.0 the public API —
anywhen, anywhenParts, AnywhenOptions, and the exported types — only
changes shape in a major release. New options arrive in minors; exact
formatted strings come from Intl and may vary between ICU versions, so
never assert on them across environments.
Node.js 18+ · Chrome 71+ · Firefox 65+ · Safari 14+ · Edge Runtime · Cloudflare Workers · Deno
CI runs the full suite on Node 20, 22, and 24. Older runtimes down to Node 18 work but are not tested on every release.