Lily Design System™

DateTime View

A datetime view is a read-only display of a formatted date and/or time using the semantic <time> element so that browsers and assistive technology can understand the underlying ISO 8601 value while users see a localized human-friendly rendering supplied by the consumer.

Use it whenever you display a timestamp (publish date, last update, event start) and want both machine-readable semantics and a presentation string that the consumer has formatted in the user's locale.

Example

Show demo markup 
<time class="date-time-view" aria-label="a read-only display of a formatted date and time">DateTimeView</time>
Usage example 
<script lang="ts">
  import DateTimeView from './DateTimeView.svelte';

  const iso = '2026-01-31T10:00:00Z';
  const formatted = new Intl.DateTimeFormat('en-US', {
    dateStyle: 'medium',
    timeStyle: 'short',
  }).format(new Date(iso));
</script>

<DateTimeView value={iso} format={formatted} label="Published" />
Show Svelte source 
// In your Svelte component:
import DateTimeView from "lily-design-system-svelte-headless/components/DateTimeView/DateTimeView.svelte";

<DateTimeView label="Label" value="Sample value" />

Usage

ISO value with consumer-formatted display:

<DateTimeView value="2026-04-27T14:30:00Z" format="April 27, 2026 at 2:30 PM" />

Children slot for richer rendering:

<DateTimeView value="2026-04-27">
  <strong>27 Apr 2026</strong>
</DateTimeView>

Falling back to the raw ISO value:

<DateTimeView value="2026-04-27T14:30:00Z" />

Props

  • value: string (required) -- ISO 8601 datetime
  • format: string (optional) -- pre-formatted display text
  • label: string (optional) -- aria-label override
  • children: slot (optional) -- content overrides format
  • ...restProps: any additional HTML attributes

Keyboard Interactions

  • None -- this is a passive read-only display.

ARIA

  • Implicit semantics from <time> with the datetime attribute
  • aria-label rendered only when the label prop is provided

When to Use

  • Use to display timestamps in articles, comments, activity feeds, and notifications.
  • Use any time you want the rendered date to be machine-readable for browsers, search engines, and assistive technology.

When Not to Use

  • Do not use for editable date inputs (use DateInput, DateTimeLocalInput, etc.).
  • Do not use for date-range displays (use DateRange).
  • Do not use to perform localization — format upstream and pass via format or children.

Headless

Provides a single <time> element with the correct datetime attribute and display text fallback chain. Locale formatting, relative-time computation, and any visual treatment are the consumer's responsibility.

Styles

The consumer styles the date-time-view class. A common pattern wraps the component to apply font-variant-numeric or letter-spacing for tabular dates.

Testing

  • Verify the component renders a <time> element with class date-time-view
  • Verify the datetime attribute equals the value prop
  • Verify display text uses children if provided, then format, then value
  • Verify aria-label is set when the label prop is provided

Advice

  • Designers: Decide whether absolute ("April 27, 2026") or relative ("3 hours ago") formatting fits the context. Pass either via format or children.
  • Developers: Always pass an ISO 8601 value to value so the underlying datetime attribute remains machine-readable, even if your display text is relative or partial.

Implementation Notes

  • Renders a <time> element so the value is machine-readable
  • Sets datetime={value} from the ISO 8601 string
  • Display text falls back: children → format → value
  • Does not perform any localization — the consumer formats the displayed text
  • Sets class="date-time-view"

Related components

  • date-time-local-input — an input for entering a date and time without time zone <input type="datetime-local">
  • date-range — paired start and end date inputs
  • review-date — a display of a content review date

References

  • MDN time element: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/time
  • ISO 8601: https://www.iso.org/iso-8601-date-and-time-format.html

Canonical contract

Generated from this component's canonical metadata — the machine-checked source the implementations are held to.

Metadata

  • Component: date-time-view
  • PascalCase: DateTimeView
  • Description: a read-only display of a formatted date and time
  • Status: beta — implemented and unit-tested in all seven frameworks with an axe-clean demo page; not yet exercised in composed flows
  • HTML tag: <time>
  • CSS class: .date-time-view
  • Interactive: no

ARIA

  • Implicit <time> semantics
  • aria-label for screen reader override (optional)

Keyboard

  • None — passive read-only display

Props

  • value: string (required) -- ISO 8601 datetime
  • format: string (optional) -- pre-formatted display text
  • label: string (optional) -- aria-label override
  • children: slot (optional) -- overrides format
  • ...restProps: any additional HTML attributes