XDSTimestamp@xds/core · Timestamp

Usage

Timestamp formats a date or time value into human-readable text. Use it to show when something was created, updated, or is scheduled — picking relative for recency, absolute for precision, or auto to let the component decide.

Best practices

GuidancePractices
DoUse the auto format in feeds and lists so recent items show “2 hours ago” and older items show the full date automatically.
DoKeep formatting consistent within the same list or table — mixing relative and absolute timestamps in the same column confuses scanning.
DoEnable isTimezoneShown when the audience spans multiple time zones, like a global team calendar or audit log.
DoUse isLive for active dashboards or real-time feeds so the relative time stays accurate without a page refresh.
Don'tDon’t display raw Unix timestamps or ISO strings to users — always pass them through Timestamp to get a human-readable format.
Don'tAvoid system_date or system_time formats in user-facing UI — they are meant for developer tools, logs, and machine-readable contexts.
Don'tDon’t disable the tooltip on relative timestamps — users expect to hover for the full date when they see “3 hours ago”.

Anatomy

ElementDescription
Formatted textrequiredThe rendered date, time, or relative label like “2 hours ago” or “Mar 21, 2025”.
TooltipA hover card showing the full absolute date and time when the display is relative.

Import

ts
import {XDSTimestamp} from '@xds/core/Timestamp'

Props

PropTypeDescription
valuerequired
string | numberThe date/time to display. Accepts Unix timestamps (seconds) or ISO 8601 strings.
format
'relative' | 'auto' | 'date' | 'date_time' | 'time' | 'system_date' | 'system_date_time' | 'system_time' (default: 'auto')Display format. 'relative' shows '2 hours ago', 'date' shows 'Mar 21, 2025', 'date_time' shows 'Mar 21, 2025, 2:51 PM', 'time' shows '2:51 PM', 'system_*' variants use ISO-style formatting, 'auto' switches from relative to date_time based on recency.
autoThreshold
number (default: 604800)Threshold in seconds for 'auto' format to switch from relative to date_time.
hasTooltip
boolean (default: true)Whether to show a tooltip with the full date/time on hover when displaying relative time.
isTimezoneShown
boolean (default: false)Whether to append the timezone abbreviation. Applies to date_time, time, system_date_time, and system_time formats.
isLive
boolean (default: false)Whether the relative time should update live (e.g. "2 min ago" → "3 min ago").
type
XDSTextType (default: 'supporting')Semantic text type from XDSText. Determines size, weight, and line-height.
size
XDSTextSizeExplicit font size override. Overrides the size from type.
color
XDSTextColor (default: 'secondary')Text color.
weight
XDSTextWeightFont weight override.

Examples

Common configurations, variations, and states.
Timestamp — AutoAuto format that shows relative time for recent dates and switches to the full date for older ones. The default choice for most use cases.
tsx
'use client';
​
import {XDSTimestamp} from '@xds/core/Timestamp';
import {XDSStack} from '@xds/core/Layout';
import {XDSText} from '@xds/core/Text';
​
export default function TimestampAutoFormat() {
  const now = Date.now() / 1000;
  return (
    <XDSStack direction="vertical" gap={4}>
      <XDSStack direction="vertical" gap={1}>
        <XDSText type="supporting" color="secondary">
          Recent — renders as relative
        </XDSText>
        <XDSStack direction="horizontal" gap={4} vAlign="center">
          <XDSTimestamp value={now - 300} format="auto" color="primary" />
          <XDSTimestamp value={now - 7200} format="auto" color="primary" />
          <XDSTimestamp value={now - 86400} format="auto" color="primary" />
        </XDSStack>
      </XDSStack>
      <XDSStack direction="vertical" gap={1}>
        <XDSText type="supporting" color="secondary">
          Older than 7 days — renders as date_time
        </XDSText>
        <XDSStack direction="horizontal" gap={4} vAlign="center">
          <XDSTimestamp value="2025-01-15T09:30:00Z" format="auto" color="primary" />
          <XDSTimestamp value="2024-06-01T14:00:00Z" format="auto" color="primary" />
        </XDSStack>
      </XDSStack>
    </XDSStack>
  );
}
Timestamp — FormatsAll display formats side by side: date, date_time, time, and their system equivalents. Use date and date_time for user-facing UI, system variants for logs and dev tools.
tsx
'use client';
​
import {XDSTimestamp} from '@xds/core/Timestamp';
import {XDSStack} from '@xds/core/Layout';
import {XDSText} from '@xds/core/Text';
​
const DATE = '2026-02-19T17:00:00Z';
​
export default function TimestampFormats() {
  return (
    <XDSStack direction="vertical" gap={4}>
      <XDSStack direction="vertical" gap={1}>
        <XDSText type="supporting" color="secondary">
          User-facing formats
        </XDSText>
        <XDSStack direction="horizontal" gap={4} vAlign="center">
          <XDSTimestamp value={DATE} format="date" color="primary" />
          <XDSTimestamp value={DATE} format="date_time" color="primary" />
          <XDSTimestamp value={DATE} format="time" color="primary" />
        </XDSStack>
      </XDSStack>
      <XDSStack direction="vertical" gap={1}>
        <XDSText type="supporting" color="secondary">
          System formats (logs and dev tools)
        </XDSText>
        <XDSStack direction="horizontal" gap={4} vAlign="center">
          <XDSTimestamp value={DATE} format="system_date" type="code" color="primary" />
          <XDSTimestamp value={DATE} format="system_date_time" type="code" color="primary" />
          <XDSTimestamp value={DATE} format="system_time" type="code" color="primary" />
        </XDSStack>
      </XDSStack>
    </XDSStack>
  );
}
Timestamp — RelativeRelative time labels from seconds to months ago, with hover tooltips showing the full date. Use in feeds, comment threads, and activity logs.
tsx
'use client';
​
import {XDSTimestamp} from '@xds/core/Timestamp';
import {XDSStack} from '@xds/core/Layout';
import {XDSText} from '@xds/core/Text';
​
export default function TimestampRelativeFormat() {
  const now = Date.now() / 1000;
  return (
    <XDSStack direction="vertical" gap={3}>
      <XDSText type="supporting" color="secondary">
        Relative timestamps (hover for full date)
      </XDSText>
      <XDSStack direction="vertical" gap={2}>
        <XDSTimestamp value={now - 5} format="relative" color="primary" />
        <XDSTimestamp value={now - 120} format="relative" color="primary" />
        <XDSTimestamp value={now - 3600} format="relative" color="primary" />
        <XDSTimestamp value={now - 86400} format="relative" color="primary" />
        <XDSTimestamp value={now - 259200} format="relative" color="primary" />
        <XDSTimestamp value={now - 90 * 86400} format="relative" color="primary" />
      </XDSStack>
    </XDSStack>
  );
}
Timestamp — TimezoneTimestamps with the timezone abbreviation appended. Enable isTimezoneShown for audiences across time zones, like audit logs or team calendars.
tsx
'use client';
​
import {XDSTimestamp} from '@xds/core/Timestamp';
import {XDSStack} from '@xds/core/Layout';
import {XDSText} from '@xds/core/Text';
​
const DATE = '2026-02-19T17:00:00Z';
​
export default function TimestampTimezone() {
  return (
    <XDSStack direction="vertical" gap={4}>
      <XDSStack direction="vertical" gap={1}>
        <XDSText type="supporting" color="secondary">
          User-facing with timezone
        </XDSText>
        <XDSStack direction="horizontal" gap={4} vAlign="center">
          <XDSTimestamp value={DATE} format="date_time" isTimezoneShown color="primary" />
          <XDSTimestamp value={DATE} format="time" isTimezoneShown color="primary" />
        </XDSStack>
      </XDSStack>
      <XDSStack direction="vertical" gap={1}>
        <XDSText type="supporting" color="secondary">
          System formats with timezone
        </XDSText>
        <XDSStack direction="horizontal" gap={4} vAlign="center">
          <XDSTimestamp value={DATE} format="system_date_time" isTimezoneShown type="code" color="primary" />
          <XDSTimestamp value={DATE} format="system_time" isTimezoneShown type="code" color="primary" />
        </XDSStack>
      </XDSStack>
    </XDSStack>
  );
}
Timestamp \u2014 ColorsTimestamp rendered in each available color variant: primary, secondary, disabled, and active.
tsx
'use client';
​
import {XDSTimestamp} from '@xds/core/Timestamp';
import {XDSStack} from '@xds/core/Layout';
import {XDSText} from '@xds/core/Text';
​
const DATE = '2026-02-19T17:00:00Z';
​
export default function TimestampColors() {
  return (
    <XDSStack direction="vertical" gap={4}>
      <XDSStack direction="vertical" gap={1}>
        <XDSText type="supporting" color="secondary">
          Primary
        </XDSText>
        <XDSTimestamp value={DATE} format="date_time" color="primary" />
      </XDSStack>
      <XDSStack direction="vertical" gap={1}>
        <XDSText type="supporting" color="secondary">
          Secondary
        </XDSText>
        <XDSTimestamp value={DATE} format="date_time" color="secondary" />
      </XDSStack>
      <XDSStack direction="vertical" gap={1}>
        <XDSText type="supporting" color="secondary">
          Disabled
        </XDSText>
        <XDSTimestamp value={DATE} format="date_time" color="disabled" />
      </XDSStack>
      <XDSStack direction="vertical" gap={1}>
        <XDSText type="supporting" color="secondary">
          Active
        </XDSText>
        <XDSTimestamp value={DATE} format="date_time" color="active" />
      </XDSStack>
    </XDSStack>
  );
}

Showcase source

tsx
'use client';
​
import {XDSTimestamp} from '@xds/core/Timestamp';
​
export default function TimestampShowcase() {
  return <XDSTimestamp value="2026-03-25T12:00:00Z" color="primary" />;
}