# 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
- Page: https://www.digitaltableteur.com/design-system/components/timestamp
- Contract: https://www.digitaltableteur.com/contracts/v1/Timestamp.contract.json

## 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

| 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.

| 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.

## Links

- Machine-readable contract (Design System Contract 1.0): https://www.digitaltableteur.com/contracts/v1/Timestamp.contract.json
- Markdown version of this page: https://www.digitaltableteur.com/design-system/components/timestamp.md
- Component index as JSON: https://www.digitaltableteur.com/design-system/components.json
- All components: https://www.digitaltableteur.com/design-system/components
- Source: The implementation lives in a private repository. This page, its Markdown twin and the contract are generated from it at build time and are the public source of truth.