DateTimeText

When to use

Wherever a date or time is shown: a creation date, a last update, an appointment time.

When not to use

• To pick a date: Use DatePicker or TimeField.
• For a countdown: Use CountdownTimer.

Anatomy

Created

8 Oct 2026

Last updated

8 October 2026 at 14:30

Time

14:30

LightDark

Copy code

import { DateTimeText, Provider } from '@bigbang/ui';

export default function Default() {
  return (
    <Provider locale="en-GB">
      <dl className="grid grid-cols-[auto_1fr] gap-x-xl gap-y-sm type-body-md">
        <dt className="text-fg-subtle">Created</dt>
        <dd>
          <DateTimeText value="2026-10-08" />
        </dd>
        <dt className="text-fg-subtle">Last updated</dt>
        <dd>
          <DateTimeText value="2026-10-08T14:30:00" dateStyle="long" />
        </dd>
        <dt className="text-fg-subtle">Time</dt>
        <dd>
          <DateTimeText value="2026-10-08T11:30:00Z" format="time" timeZone="Europe/Istanbul" />
        </dd>
      </dl>
    </Provider>
  );
}

1. <time> element: Its datetime attribute holds the machine-readable value.
2. Text: The date, time or relative time formatted in the Provider language.

Behaviour

• The format comes from Intl.DateTimeFormat in the Provider language: “8 Eki 2026 14:30” in Turkish, “8 Oct 2026, 14:30” in English.
• A plain ISO date (“2026-10-08”) is a local calendar day; it does not shift a day with the time zone.
• The relative format uses Intl.RelativeTimeFormat (“yesterday”, “2 hours ago”) and refreshes every 30 seconds; changed text cross-fades.
• With now, relative time counts from it and does not refresh (for server rendering and tests).

Guidelines

• Use exact time in records and tables, relative time in feeds.
• Use one format per list.
• If the zone matters, set timeZone and say it on the page.

Content

DateTimeText has no text of its own; month and day names come from Intl.

Related components

• Timeline: Event times.
• DatePicker: Picking a date.