Dates & times

InstallCopy Anchor Link

pnpm exec vegastack-design verify relative-time

pnpm dlx shadcn@4.21.0 add @vegastack/relative-time

UsageCopy Anchor Link

For stable relative text from the first render, pass a request timestamp with the timezone: <TimeZoneProvider timeZone={zone} referenceNow={requestNow}>. Serialize the same numeric requestNow into the client tree. Uncontrolled timestamps then share one live clock; passing now directly remains a controlled clock. Without a request reference, the server renders a clock-free absolute date ("Sep 25", "Sep 25 · 2:30 PM", "Due Sep 30"), so crawlers and no-JS HTML keep the date; the browser then switches to the relative words.

import {
  DateTime,
  DueLabel,
  Duration,
  RelativeTime,
} from "@/components/ui/relative-time";
import { formatDate, formatRelative, groupByDay } from "@/lib/date-time";

<RelativeTime date={row.updatedAt} format="minimal" />; // "2m"
<DateTime date={task.createdAt} />; // "Sep 25"
<DueLabel date={task.dueAt} />; // "Overdue 2d"
formatRelative(row.updatedAt, { timeZone }); // plain string, server or client

The formatting functions live in @/lib/date-time and are plain — call them in server components, route handlers, emails and client code alike. The components wrap them in a semantic <time> and add the absolute time in a hover tooltip ("Sep 25, 2026 · 2:30 PM IST").

Shared rulesCopy Anchor Link

• The year shows only when it is not the current year.
• 12-hour clock with no leading zero: "9:04 AM".
• Minimal units s m h d w mo y, no space before the unit.
• Calendar days use the viewer's time zone (timeZone option on every function).
• Anything under 45 seconds reads "now".
• Built on Intl, locale-ready; English for now.
• Set in the body font with proportional figures, like the text around them. Tabular figures are for live timers (the media player's clock), not for dates.

Where to use whatCopy Anchor Link

AnatomyCopy Anchor Link

Dates & times exports several parts. Every exported part, with the data-slot it renders (generated from the canonical source):

ExamplesCopy Anchor Link

formatRelativeCopy Anchor Link

now · 2m · 3h · 5d · 1w · 2mo · 1y · in 2d. style: "suffix" gives "2m ago"; style: "long" gives "2 minutes ago".

formatDurationCopy Anchor Link

Input in seconds (or unit: "milliseconds"). At most two units; seconds drop once minutes exist. clock: true reads "1:15:04"; style: "long" spells the units for sentences and emails — "1 hour 15 minutes", "7 days".

formatDate and formatTimeOfDayCopy Anchor Link

Today · Tomorrow · Yesterday · a weekday within ±6 days ("Mon", "Last Fri") · "Sep 25" · "Dec 20, 2026". looseFuture: true turns far-future dates into "in 2 weeks"; absolute: true always prints the date.

formatLongDate is the page-header date — "Thursday, September 24", with the year outside the current year; locale: "en-IN" (or en-GB) reads "Thursday, 24 September". hourOfDay returns the hour (0–23) on the viewer's clock, for a greeting or a working-hours check.

formatDateTime and formatDateRangeCopy Anchor Link

formatDateTime joins the day and time with a middle dot ("Today · 2:30 PM"); use separator: "comma" inside sentences. formatDateRange collapses what the ends share.

formatDueLabelCopy Anchor Link

Returns { label, tone } — tone is overdue, soon (today/tomorrow) or normal.

Calendar daysCopy Anchor Link

A day stored without a time ("2026-10-08": a due date, a date field) is not an instant, so it never goes through a zone. formatCalendarDate(day, { locale, format }) writes the day it names — short "Oct 8, 2026", long "October 8, 2026", numeric "10/8/2026" — for a reader in UTC−8 and in UTC+13 alike, and "" for an invalid day. parseCalendarDay(day) gives the local-midnight Date a DatePicker takes, and toCalendarDay(date) turns the picked Date back into the day, with no shift; toCalendarDay(instant, { timeZone }) is the day an instant falls on in a zone ("today" for a viewer).

formatCalendarDate("2026-10-08"); // "Oct 8, 2026"
toCalendarDay(parseCalendarDay("2026-10-08")!); // "2026-10-08"
toCalendarDay(new Date(), { timeZone }); // today, for this viewer

groupByDayCopy Anchor Link

Buckets items into Today / Yesterday / This week / Last week / Earlier (weeks start Monday; empty groups are dropped). Each group has a stable key and a label.

ComponentsCopy Anchor Link

<RelativeTime>, <DateTime> and <DueLabel> follow the shared live clock; explicit RelativeTime.now and DateTime.options.now stay controlled, and RelativeTime.refresh={false} freezes at the moment it mounts. These date components show the absolute time in a hover tooltip unless title={false}. <Duration> formats the supplied length without a live clock or absolute-time tooltip.

Time zoneCopy Anchor Link

Day boundaries follow the viewer. Write the browser zone to a tz cookie, read it on the server with the org zone from app config as the fallback, and provide it to the tree:

// app/layout.tsx (server)
import { cookies } from "next/headers";
import {
  TimeZoneProvider,
  TimeZoneScript,
} from "@/components/ui/relative-time";
import { TIME_ZONE_COOKIE, getTimeZone } from "@/lib/date-time";
import { config } from "@/config";

const timeZone = getTimeZone(
  (await cookies()).get(TIME_ZONE_COOKIE)?.value,
  config.orgTimeZone,
);

<body>
  <TimeZoneScript />
  <TimeZoneProvider timeZone={timeZone} referenceNow={Date.now()}>
    {children}
  </TimeZoneProvider>
</body>;

TimeZoneScript writes the cookie on load and again when the tab becomes visible, so a changed zone reaches the next request. Client code reads the zone with useTimeZone(); server code passes timeZone to each function.

RelativeTime renders a semantic <time dateTime> element and self-updates on a timer while the date is recent, with the exact date and time in the hover. It uses the platform-native Intl APIs — no date-fns or other date dependency.

RelativeTime formatsCopy Anchor Link

Past and future instants, in the house compact form: now under a minute, then 19m ago, 3h ago, 2d ago, 3w ago, 5mo ago, 1y ago; future dates read in 2d. No unit carries a period — the old Intl short style (19 min. ago) is gone.

Format variantsCopy Anchor Link

format picks the form of the ago label: suffix (the default, 19m ago), minimal for dense tables and chips (19m), and long for sentences (19 minutes ago). The deprecated unitStyle maps long to format="long" and everything else to the default.

ModesCopy Anchor Link

mode="ago" (default) is duration-relative — "2h ago", "in 3d". mode="day" is calendar-relative — "today", "yesterday", "tomorrow", and an absolute date ("March 15", "March 15, 2025") once a date is further out.

StatesCopy Anchor Link

By default the absolute date-time is revealed in a Tooltip on hover or focus. Pass a string to title for a custom label, or title={false} to drop the tooltip.

Tooltip delayCopy Anchor Link

tooltipDelay (ms) sets how long the pointer must hover before the absolute-date tooltip opens. It defaults to the app-wide tooltip delay (TIMINGS.tooltipOpenDelayMs, 250ms), so it matches every other tooltip. Ignored when title={false}.

LocalizationCopy Anchor Link

locale localizes what Intl words: the mode="day" labels and dates and format="long". The compact ago form (2h ago) is the house form everywhere, so a dense column reads the same in every locale. Without locale it formats in DEFAULT_LOCALE (en-US), never the runtime's: a server under another LANG then renders the same text as the browser, so the page hydrates without a mismatch. Pass the reader's locale explicitly to localize.

Standalone labelCopy Anchor Link

Inside a sentence the relative words read lower-case ("due today"). A label that stands on its own takes capitalize ("Today"). With title={false} it has no tooltip, so it is plain inline text at the line's height rather than a 24px pointer target.

Fixed time zoneCopy Anchor Link

timeZone (an IANA name) decides which calendar day an instant falls on, and formats the server's first render and the tooltip in the same zone — so a server in UTC and a reader in IST agree on what "today" is. Omit it to follow the runtime's zone.

Day with timeCopy Anchor Link

In mode="day", withTime appends the time of day ("Today, 10:00 AM"). formatOptions shapes the absolute date shown beyond yesterday and tomorrow — { day: "numeric", month: "short" } reads "6 Jan" in en-IN — and the year is added only when the date is in another year.

Live updatesCopy Anchor Link

When now is left unset, timestamps subscribe to one shared ten-second clock, and each one re-renders only when its own label can change: every tick within an hour of now, once a minute within a day, and on quarter-hour boundaries beyond that (every real zone offset is a multiple of 15 minutes, so day words still flip at the viewer's midnight). A time of day and an absolute date never subscribe. No per-row timers are allocated. The example below is intentionally live — it seeds a timestamp 30s in the past and climbs as you watch. Pass refresh={false} to opt out.

Application groups, due badges and date-picker presets can share that same clock through useDateTimeNow(), exported by this registry item. It returns epoch milliseconds, or undefined until hydration when no request reference was provided. With TimeZoneProvider.referenceNow, server output and the hydration render receive the same reference. Keep a placeholder for a missing reference; do not replace it with a separate Date.now() during rendering.

import { DateTime, useDateTimeNow } from "@/components/ui/relative-time";

export function CurrentTime() {
  const nowMs = useDateTimeNow();
  return nowMs === undefined ? (
    <span>…</span>
  ) : (
    <DateTime date={nowMs} variant="time" />
  );
}

Format the instant in the viewer's effective zone. The hook and uncontrolled RelativeTime instances share one timer; a RelativeTime now={...} remains controlled.

DeterminismCopy Anchor Link

The displayed value depends on the current time. For tests, SSR snapshots, or Storybook, pass a fixed now (epoch ms) to render deterministically — this also disables the refresh timer.

<RelativeTime date={ts} now={Date.UTC(2026, 0, 15, 12, 0, 0)} refresh={false} />

PlaygroundCopy Anchor Link

Switch the formatting mode and the instant being rendered, then copy the generated JSX.

<RelativeTime date={new Date(Date.now() - 5 * 60_000)} />

API ReferenceCopy Anchor Link

Server renderingCopy Anchor Link

Pass a serialized request timestamp as TimeZoneProvider.referenceNow to render relative text identically on the server and the hydration render. The shared clock then updates live labels. Without that reference, the server renders the clock-free absolute date and the browser replaces it with the relative label. now remains a controlled clock, and refresh={false} freezes at mount time, never at an older request reference.

DateTime and DueLabel use the same request/live reference, so calendar words and due tones update across midnight in the effective zone. DateTime.options.now is an explicit controlled reference; absolute, relativeDay and other formatting choices retain their meanings. Without a request reference, they render the clock-free absolute date (a time of day and an absolute date are exact on the server). These components do not suppress hydration mismatches; absolute tooltip labels retain their full date, time and zone.

AccessibilityCopy Anchor Link

• Renders a semantic <time dateTime="…"> so the machine-readable ISO timestamp is always present for assistive tech, even as the visible text updates.
• When the absolute-date Tooltip is enabled, the <time> is made focusable (tabindex="0") so keyboard users can reveal it; :focus-visible shows a 2px ring (outline-ring) — never outline: none alone.
• Color is inherited from context — the component never encodes meaning in color, so the relative string stands on its own.

focusable controls whether the timestamp takes a tab stop to open its absolute-date Tooltip. It defaults to true standalone, and to whatever an enclosing TruncationFocusProvider sets — false for a grid or list host, where 50 rows would otherwise mean 50 extra tab stops on top of that host's own roving focus. The machine-readable dateTime attribute is there either way.

Do / Don'tCopy Anchor Link