README.md
July 23, 2026 · View on GitHub
anywhen
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日"
install
npm install anywhen
usage
anywhen(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");
recipes
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",
});
modes
The mode option picks the rendering strategy. Default is "smart".
smart
Context-aware. Picks the most readable format based on distance from now — covers past and future.
Calendar labels are symmetric — past and future read the same way:
anywhen(date, { locale: "en" });
// < 45s → "now"
// < 1 hour → "10 minutes ago" / "in 10 minutes"
// same day → "today, 14:35"
// yesterday → "yesterday, 09:00"
// tomorrow → "tomorrow, 09:00"
// within 7 days → "Wednesday, 11:20" (past or future)
// older / further → "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 clock
Reads: 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".
absolute
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.
relative
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.
options
| 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.
thresholds
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 minutes
In smart mode thresholds.second widens the "now" window and
thresholds.minute the sub-hour minutes window, symmetrically in both
directions. Calendar labels (today, yesterday, tomorrow, weekday) and the
absolute fallback are not affected.
parts
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,
);
React / Next.js
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).
locales
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.
vs the alternatives
| anywhen | dayjs | date-fns | |
|---|---|---|---|
| gzip | ~1.3kb | ~7kb | ~20kb |
| locale data bundled | no | yes | yes |
| locales | 200+ | 140 | 100 |
| dependencies | 0 | 0 | 0 |
stability
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.
compatibility
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.
the any family
anywhen is part of any family — a set of tiny, zero-dependency, native-first utilities.