Timestamp

Formats an ISO calendar date, instant, Unix timestamp, or Date into human-readable text: relative for recency, absolute for precision, or auto to switch between them. Date-only values keep their calendar date across runtime timezones, and timeZone is ignored for them.

Status: stable. Group: display. Markdown version: /design-system/components/timestamp.md

When to use

Timestamp renders machine-readable date and time values as localized human text. Use relative or auto formats for recent activity, absolute formats when precision matters, and system formats for technical contexts. Date-only input stays on the same calendar date regardless of the runtime timezone or timeZone.

When not to use

Do not wrap it in another <time> or add a title around it; it renders its own <time> and sets title itself on relative output.
Do not use live for values that will not change meaningfully while on screen (absolute dates); it only re-renders relative/auto output.

Look-alikes

The contract names no look-alike with a deciding condition.

Props

Timestamp props
Prop	Type	Default	Description	Required
`value`	`string \| number \| Date`	none	The date/time to display: ISO 8601 calendar date or instant, Unix seconds, or Date.	Yes
`format`	`"auto" \| "date" \| "time" \| "relative" \| "date_time" \| "system_date" \| "system_date_time" \| "system_time"`	`auto`	Display format.	No
`autoThreshold`	`number`	`604800`	Seconds after which `auto` switches from relative to date_time.	No
`size`	`"xs" \| "s" \| "xxs" \| "m"`	`s`	Text-ladder size.	No
`tone`	`"default" \| "muted"`	`muted`	Color role: body text or muted metadata.	No
`showTimezone`	`boolean`	`false`	Append the timezone abbreviation (date_time/time/system equivalents).	No
`tooltip`	`boolean`	`true`	Full date for relative output: a native tooltip (title) for pointer users plus the same text, visually hidden, inside the <time> for screen readers.	No
`live`	`boolean`	`false`	Keep relative output ticking while mounted.	No
`now`	`string \| number \| Date`	none	Reference "now" for relative/auto output. Defaults to render time; pass a fixed value in stories/tests for deterministic output.	No
`locale`	`string`	none	Locale override; defaults to the active site language.	No
`timeZone`	`string`	none	IANA time zone for the shown date and time, for example "Europe/Helsinki". Defaults to the runtime's zone, which is UTC on a server render: set it when the moment must read the same everywhere (a business's local time). Ignored for a date-only (YYYY-MM-DD) value, which has no time of day and always shows its own calendar date.	No
`className`	`string`	`""`	Optional className passthrough.	No

Variants

Available sizes: xxs, xs, s, m (default s).
Available tones: default, muted (default muted).
Allowed format values: auto, date, time, relative, date_time, system_date, system_date_time, system_time (default auto).

Invalid combinations

The contract records no invalid combinations.

Keyboard

The contract records no keyboard interaction.

Rules

Every item under When not to use is a MUST NOT. MUST and SHOULD follow RFC 2119.

Timestamp rules
Level	Rule	How it is checked
MUST	ARIA: Renders a semantic <time> element with a machine-readable dateTime attribute that preserves date-only versus instant precision.	Not yet verified: no evidence record. WCAG 4.1.2.
MUST	ARIA: Relative output carries the full date when tooltip is true: as a native tooltip (title) for pointer users and as visually hidden text inside the <time>, so screen readers announce it too. The element is not focusable, so sighted keyboard and touch users see only the relative text. A date-only value gets a date-only full date (no time of day).	Not yet verified: no evidence record. WCAG 4.1.2.
MUST	Required stories produce no axe violations at the configured severity.	Automated by `npm run test:stories:matrix:ci`. WCAG 2.5.8.
MUST	The accessibility tree (role, name, state) matches the committed snapshot for every required story.	Automated by `npm run test:stories:matrix:ci`. WCAG 1.3.1, 4.1.2.
MUST	The component remains legible and operable under a real browser forced-colors: active pass.	Automated by `npm run test:stories:hc`.
MUST	A human completed an end-to-end accessibility review of this component.	Manual review, last on 2026-11-04.
SHOULD	Use auto for activity metadata that should read relatively while recent and become precise as it ages.	Not stated in the contract.
SHOULD	Use date or date_time when readers must compare or cite an exact calendar value.	Not stated in the contract.
SHOULD	Pass date-only content as YYYY-MM-DD; its calendar date is preserved across runtime timezones and timeZone does not shift it.	Not stated in the contract.
SHOULD	Enable showTimezone for time-bearing values when the reader needs to know which timezone applies.	Not stated in the contract.
SHOULD NOT	Do not wrap Timestamp in another time element or duplicate its machine-readable dateTime value.	Not stated in the contract.
SHOULD NOT	Do not enable live for static historical values; periodic updates should be reserved for relative time that changes on screen.	Not stated in the contract.

Install and import

Install: npm install @digitaltableteur/react (version 0.9.1, restricted access on npm).
Import: import { Timestamp } from "@digitaltableteur/react";
Entry point: @digitaltableteur/react/content exports it too.
Styles: import @digitaltableteur/react/style.css once at the app boundary.
Also available as the custom element <dt-timestamp>; see the custom elements manifest.