Relative time

Free · MIT

"3 minutes ago" / "in 6 days", kept fresh, with the exact time on hover. Shows the date until the clock is known. format shows an absolute time instead ("5 Nov 2026, 14:03"), in the locale, with the same server-safe gate.

Markdown

Preview

Install

With the Candor CLI

First time? Get started sets up the registry and theme. Or with shadcn directly: npx shadcn@latest add @candor/relative-time

Brings in: locale

Usage

TSX · The example above

"use client"

import { RelativeTime } from "@/components/relative-time"

const minutesAgo = (m: number) => new Date(Date.now() - m * 60_000)

export default function Example() {
  return (
    <ul className="flex flex-col gap-1 text-sm">
      <li>Sent <RelativeTime date={minutesAgo(0.2)} /></li>
      <li>Updated <RelativeTime date={minutesAgo(14)} /></li>
      <li>Created <RelativeTime date={minutesAgo(60 * 30)} /></li>
    </ul>
  )
}

<RelativeTime>

Prop	Type	Default	Description
daterequired	`Date \| string`	—	When it happened. Shown as "5 minutes ago", with the exact time on hover.
bare	`boolean \| undefined`	false	Drop "ago" and "in", for tight spaces: "5 minutes".
format	`"relative" \| DateStyle \| undefined`	"relative"	"relative" (the default), or an absolute "date", "datetime" or "time" in the locale.
className	`string \| undefined`	—	Extra classes for the outer element.

Functions

formatRelative(date: Date, now = new Date(), { locale, justNow = relativeTimeStrings.justNow, bare = false }: { locale?: string | undefined; justNow?: string | undefined; bare?: boolean | undefined } = {})

"5 minutes ago", "in 6 days", in the locale (the runtime's own when left out). bare drops the direction for tight spaces: "5 minutes".

useNow()

The current time in milliseconds, updated every 30 seconds; null while rendering on the server.

Strings

The fixed words, in English by default. Change any of them under relativeTime in <LocaleProvider strings={{ … }}>; the table is exported as relativeTimeStrings.

Key	English
justNow	just now