Timestamp

Every date and time in one component. Hover or focus shows the full local date, time and zone; a click, Enter or Space copies an explicit string that still makes sense when pasted into an email read in another zone.

Formats

Compact for dense lists, Relative for activity, Contextual for chat and schedules, Absolute for audit, billing and exports, Time under a day divider, Date for calendar dates. Today, yesterday and the year come from calendar days in your zone.

Δ	COMPACT	RELATIVE	CONTEXTUAL	TIME	ABSOLUTE	DATE
−20 s
−5 m
−3 h
−30 h
−3 d
−10 d
−400 d
+5 m
+1 d

Viewer settings

Locale

Time zone

Clock

Relative
Contextual
Absolute

Date-only values

A YYYY-MM-DD value is a calendar date: no time, no zone, never shifted a day.

Due (Date)
Due (Relative)
Due (Compact)

Copy

Click the time, then paste below. The copy carries the weekday, the year, the zone name when your locale has one, and the UTC offset, with plain spaces.

Sent

Last copied: —

Inside a link

A button inside a link is invalid HTML, so pass copyable={false}: the tooltip still shows on hover, and the link keeps the label in its name.

Release notes, posted

Clickable row

The row opens on click, or on Enter or Space when it has focus; a click, Enter or Space on the timestamp copies and stops there. Row opens: 0

Invoice #1042

Inside a dialog

Focus a timestamp in the dialog: Escape closes the tooltip first, and a second Escape closes the dialog. “Copied” is announced inside the dialog.

Usage

Timestamp

import { Timestamp, TimestampFormat, TimestampProvider } from '@creo-team/buzz-ui/client'

// Once, near the root, from the signed-in user's settings:
<TimestampProvider locale={user.locale} timeZone={user.timeZone} hour12={user.hour12}>
  <App />
</TimestampProvider>

// Anywhere:
<Timestamp value={comment.createdAt} />                                    // 5 minutes ago
<Timestamp value={message.sentAt} format={TimestampFormat.Contextual} />    // Today at 3:04 PM
<Timestamp value={invoice.issuedAt} format={TimestampFormat.Absolute} />    // Oct 1, 2026, 3:04 PM
<Timestamp value={task.dueOn} format={TimestampFormat.Date} />              // '2026-10-05' → Mon, Oct 5, 2026

// Inside a link, keep it non-interactive:
<a href={post.url}>Posted <Timestamp value={post.createdAt} copyable={false} /></a>

Reporting issues to your logger

"use client"
// Wrap the provider to pass onError (a function) from your app's logger.
export function AppTimestampProvider({ children, ...settings }: TimestampProviderProps) {
  return <TimestampProvider {...settings} onError={issue => logger.warn(issue, 'timestamp issue')}>{children}</TimestampProvider>
}

Timestamp Props

Prop	Type	Default	Description
`value`*	`Date \| number \| string`	—	A Date, epoch milliseconds, an ISO 8601 instant with an offset, or a YYYY-MM-DD calendar date.
`format`	`TimestampFormat`	`TimestampFormat.Relative`	Compact, Relative, Contextual, Time, Absolute or Date.
`copyable`	`boolean`	`true`	Set false inside a link or stretched-link card.
`direction`	`TooltipDirection \| Side`	`TooltipDirection.Top`	Side the tooltip prefers.
`locale`	`string`	`provider, else browser`	BCP 47 locale. Invalid values fall back and are reported.
`timeZone`	`string`	`provider, else viewer`	IANA zone. Invalid values fall back and are reported.
`hour12`	`boolean`	`provider, else locale`	Force a 12-hour (true) or 24-hour (false) clock.
`onCopied`	`(text: string) => void`	—	Called with the copied text after a successful copy.
`className / id / data-* / ref`	`—`	—	Applied to the root span, which exists in every state.

TimestampProvider Props

Prop	Type	Default	Description
`locale`	`string`	—	Validated once; an invalid tag falls back to the browser locale and is reported.
`timeZone`	`string`	—	Validated once; an invalid zone falls back to the viewer’s zone and is reported.
`hour12`	`boolean`	`locale convention`	Force a 12-hour or 24-hour clock.
`messages`	`Partial<TimestampMessages>`	—	Localize the hints, "Copied" and failure text.
`onError`	`(issue: TimestampIssue) => void`	—	Invalid values, invalid settings and copy failures, for your logger.

Full API: /components/timestamp/api