anywhen API reference

anywhen is a tiny date formatter built entirely on the native Intl browser API. One function, one options object, three modes. Stable since 1.0 — the public API follows semver.

The browser already knows how to format dates in 200+ languages. anywhen just makes that API pleasant to use.

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"

npm install anywhen
# or
pnpm add anywhen
# or
yarn add anywhen

Or take the whole family at once with npm install anyfamily.

The single entry point. Pass a date, optionally pass options.

anywhen(input)
anywhen(input, options?)

anywhen(date)
// runtime locale, smart mode

anywhen(date, { locale: 'en' })
// "yesterday, 2:35 PM"

anywhen(date, { mode: 'relative', locale: 'en', numeric: true })
// "1 day ago"

anywhen(date, {
  mode: 'absolute',
  locale: 'en',
  format: { weekday: 'long', month: 'long', day: 'numeric', year: 'numeric' },
})
// "Friday, February 5, 2016"

Same arguments as anywhen(), but returns the output as { type, value, unit? } parts instead of a string — style the number apart from the unit, or rebuild the output your own way. New in 1.0.

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,
)

Note: part values keep the original Intl characters — the space before AM/PM can be U+202F (narrow no-break space), which some engines replace with a regular space in the joined string.

The mode option picks the rendering strategy. Each mode reads only the options that apply to it — the rest are ignored.

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: { month: 'long', year: 'numeric' },
  timeZone: 'Europe/Belgrade',
})
// "February 2016"

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
// "1 week ago"

anywhen(date, { mode: 'relative', locale: 'en', style: 'short' })
// "3 hr. ago"

anywhen(date, { mode: 'relative', locale: 'en', style: 'narrow' })
// "3h ago"

Each unit is shown while the distance from now is below its cutoff, in seconds. Defaults: second: 45, minute: 2700, hour: 79200, day: 518400, week: 2160000, month: 28512000. New in 1.0.

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.secondwidens the "now" window and thresholds.minute the sub-hour minutes window, symmetrically in both directions. Calendar labels (today, yesterday, tomorrow, weekday) are not affected.

By default, smart and relative modes use the current time. In React SSR or Next.js, pass a stable now value to avoid hydration drift.

import { anywhen } from 'anywhen'

export function PostMeta({ createdAt, requestTime }: {
  createdAt: string
  requestTime: string
}) {
  return (
    <time dateTime={createdAt}>
      {anywhen(createdAt, {
        locale: 'en',
        now: requestTime,
        timeZone: 'Europe/Belgrade',
      })}
    </time>
  )
}

timeZone controls both the displayed clock and the smart calendar boundaries for today, yesterday, and weekday output.

In React, anyfamily-react's useAnywhen also keeps relative output from going stale — it re-renders on an interval so "3 minutes ago" stays true.

All inputs accept three formats interchangeably.

// Date object
anywhen(new Date())

// Unix timestamp (milliseconds)
anywhen(Date.now())
anywhen(1704499200000)

// ISO string
anywhen('2016-02-05T14:00:00Z')
anywhen('2016-02-05')

Same calls in a few languages — no extra setup, no locale files.

// smart mode
anywhen(date, { locale: 'de' })   // "gestern, 14:35"
anywhen(date, { locale: 'ru' })   // "вчера, 14:35"
anywhen(date, { locale: 'fr' })   // "hier, 14:35"

// absolute mode
anywhen(date, { mode: 'absolute', locale: 'ja' })   // "2016年2月5日"
anywhen(date, { mode: 'absolute', locale: 'ar' })   // "٥ فبراير ٢٠١٦"
anywhen(date, { mode: 'absolute', locale: 'ru' })   // "5 февр. 2016 г."

// relative mode
anywhen(date, { mode: 'relative', locale: 'de' })   // "vor 3 Stunden"
anywhen(date, { mode: 'relative', locale: 'fr' })   // "il y a 3 heures"
anywhen(date, { mode: 'relative', locale: 'tr' })   // "3 saat önce"

Pass any valid BCP 47 language tag — including regional variants like en-GB, zh-TW, or pt-BR. Locale is optional; when omitted, native Intl uses the runtime locale. Fallback arrays like ['sr-Latn-RS', 'en'] also work.

anywhen uses Intl.RelativeTimeFormat and Intl.DateTimeFormat — both widely supported.

A few things worth knowing before you ship: