Smart Formatting
Context-aware formatting that automatically picks the best representation based on how far away the date is.
Just now
whenny(now).smart()just now
5 minutes ago
whenny(fiveMinutesAgo).smart()5 minutes ago
1 hour ago
whenny(oneHourAgo).smart()5:50 AM
Yesterday
whenny(yesterday).smart()Yesterday at 6:50 AM
Last week
whenny(lastWeek).smart()Jan 27
Next week
whenny(nextWeek).smart()Tuesday at 6:50 AM
Relative Time
Human-readable time distances, with an auto-updating React hook.
Past (5 min ago)
whenny(fiveMinutesAgo).relative()5 minutes ago
Past (yesterday)
whenny(yesterday).relative()yesterday
Future (next week)
whenny(nextWeek).relative()in 6 days
Future (next month)
whenny(nextMonth).relative()in 4 weeks
This value updates automatically based on the interval you configure
Format Presets
Built-in presets for common formatting needs, plus custom templates with tokens.
Short
whenny(now).short()Feb 03
Long
whenny(now).long()February 03, 2026
Time
whenny(now).time()6:50 AM
DateTime
whenny(now).datetime()Feb 03, 6:50 AM
ISO
whenny(now).iso()2026-02-03T06:50:04.089Z
Custom Templates
Use tokens to build any format you need.
Weekday + Full date
whenny(now).format('{weekday}, {monthFull} {day}')Tuesday, February 03
Ordinal day
whenny(now).format('{monthFull} {dayOrdinal}, {year}')February 3rd, 2026
Numeric
whenny(now).format('{month}/{day}/{year}')02/03/2026
24-hour time
whenny(now).format('{hour24}:{minute}:{second}')06:50:04
Available tokens:
{year} {month} {day} {hour} {hour24} {minute} {second} {AMPM} {ampm} {weekday} {weekdayShort} {monthFull} {monthShort} {dayOrdinal}Date Comparison
Compare two dates and get human-readable descriptions of the difference.
Smart comparison
compare(yesterday, now).smart()1 day before
Days difference
compare(yesterday, now).days()-1 days
Hours difference
compare(yesterday, now).hours()-24 hours
Days between
compare(lastWeek, nextWeek).days()-14 days
Duration Formatting
Format time durations (in seconds) in various styles.
Long
duration(3661).long()1 hour, 1 minute, 1 second
Compact
duration(3661).compact()1h 1m 1s
Clock
duration(3661).clock()1:01:01
Human
duration(7200).human()about 2 hours
45 seconds
duration(45).long()45 seconds
2 hours
duration(7200).human()about 2 hours
1 day
duration(86400).human()about 24 hours
Countdown Timer
Live countdown to a future date using the useCountdown hook.
Countdown to New Year 2027
0
Days
0
Hours
0
Minutes
0
Seconds
useCountdown(targetDate) → { days: 0, hours: 0, minutes: 0, seconds: 0 }Calendar Helpers
Utility functions for common calendar operations.
Is today?
calendar.isToday(now)true ✓
Is weekend?
calendar.isWeekend(now)false
Is business day?
calendar.isBusinessDay(now)true ✓
Is past?
calendar.isPast(yesterday)true ✓
Is future?
calendar.isFuture(nextWeek)true ✓
Days until next week
calendar.daysUntil(nextWeek)6 days
Start of month
calendar.startOf(now, 'month')February 01, 2026
End of month
calendar.endOf(now, 'month')February 28, 2026
Installation
Two ways to add Whenny to your project.
NPM Package
Traditional installation as a dependency.
npm install whenny whenny-reactshadcn Style (Recommended)
Copy code directly into your project for full ownership.
npx whenny init
npx whenny add relative smart calendar