XDS — Design System

Timestamp@xds/core · XDSTimestamp v0.0.13

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.

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

Best practices

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

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" />;
}

Usage

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

Best practices

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

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> ); }

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> ); }

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> ); }

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> ); }

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> ); }