formatDistanceToNow()

formatDistanceToNow(input, options?): string

Defined in: utils/date/formatDistanceToNow.ts:61

Format the distance between the given date and "now" (by default the current time) into a small human-readable string.

The output is intentionally simple and dependency-free:

• just now (for differences under ~5 seconds)
• X seconds
• X minutes
• X hours
• X days
• X months (approximate, based on 30-day months)
• X years (approximate, based on 12-month years)

Parameters

input

The target date as a Date instance or timestamp (ms since epoch).

number | Date

options?

FormatDistanceToNowOptions = {}

Additional configuration for suffix handling and reference time.

Returns

string

A human-readable distance like "3 minutes ago", "in 2 days" or "just now".

Examples

formatDistanceToNow(new Date(Date.now() - 1000 * 60)); // "1 minute ago"
formatDistanceToNow(Date.now() + 1000 * 60 * 60 * 5);  // "in 5 hours"

// Without suffix:
formatDistanceToNow(Date.now() + 1000 * 60 * 10, { addSuffix: false });
// -> "10 minutes"