anywhen

Tiny human-readable date formatter built on native Intl.
Turn dates into "now", "yesterday, 2:35 PM", "через 3 часа", or "2016年2月5日".

▸ live demo · ▸ any family

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.

calendars and eras

Non-Gregorian calendars need no extra API. Pick the calendar with the BCP 47 -u-ca- extension on locale, and ask for the era through format — both are passed straight to Intl.DateTimeFormat.

anywhen(date, {
  mode: "absolute",
  locale: "ja-JP-u-ca-japanese",
  format: { era: "short", year: "numeric", month: "short", day: "numeric" },
});
// "平成28年2月5日"

anywhen(date, { mode: "absolute", locale: "th-TH-u-ca-buddhist" });
// "5 ก.พ. 2559"

anywhen(date, { mode: "absolute", locale: "en-US-u-ca-islamic-umalqura" });
// "Rab. II 26, 1437 AH"

anywhen(date, { mode: "absolute", locale: "zh-TW-u-ca-roc", format: { era: "short", year: "numeric", month: "short", day: "numeric" } });
// "民國105年2月5日"

anywhenParts reports the era as its own part, so it can be styled apart from the year:

anywhenParts(date, {
  mode: "absolute",
  locale: "en-u-ca-gregory",
  format: { era: "short", day: "numeric", month: "short", year: "numeric" },
});
// [… { type: "year", value: "2016" }, { type: "literal", value: " " }, { type: "era", value: "AD" }]

Two limits worth knowing:

Absolute mode only. Smart mode uses its own fixed date shape and ignores format, so eras do not appear in its absolute fallback.
eraDisplay is not usable yet. The option is still Stage 2 and current engines ignore it silently — it never reaches resolvedOptions(). Once it ships it will work through format with no change to anywhen.

Smart-mode day boundaries (today, yesterday, weekday) are computed on Gregorian days. Every calendar Intl ships switches days at local midnight too, so the boundaries line up — only the printed labels differ.

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.

Name		Name	Last commit message	Last commit date
Latest commit History 78 Commits
.github		.github
demo		demo
scripts		scripts
src		src
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
jsr.json		jsr.json
logo.png		logo.png
package.json		package.json
pnpm-lock.yaml		pnpm-lock.yaml
tsconfig.json		tsconfig.json
tsdown.config.ts		tsdown.config.ts
vitest.config.ts		vitest.config.ts

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

anywhen

install

usage

recipes

modes

smart

absolute

relative

options

thresholds

parts

React / Next.js

locales

calendars and eras

vs the alternatives

stability

compatibility

the any family

About

Releases

Packages

Contributors

Languages

Folders and files

Latest commit

History

Repository files navigation

anywhen

install

usage

recipes

modes

smart

absolute

relative

options

thresholds

parts

React / Next.js

locales

calendars and eras

vs the alternatives

stability

compatibility

the any family

About

Topics

Resources

Code of conduct

Contributing

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages