Skip to main content

datetime Renderer

renderAs: 'datetime' formats a combined date-and-time value using Intl.DateTimeFormat. It adds relativeTime support for showing values like "3 days ago" alongside or instead of the absolute timestamp.

Core Examples​

Basic Datetime​

ISO datetime strings formatted with medium (default) and short presets.

Name
Posted
Updated
Aurora Chen
Mateo Silva
Priya Nair
{ key: 'postedAt',  renderAs: 'datetime', renderAsOptions: { parseMode: 'iso-datetime' } }
{ key: 'updatedAt', renderAs: 'datetime', renderAsOptions: { parseMode: 'iso-datetime', formatPreset: 'short' } }

Relative Time​

relativeTime: true uses Intl.RelativeTimeFormat to compute "3 months ago", "in 2 days" etc. relativeDisplay: 'both' stacks the absolute value above the relative label:

Left: relative-only display. Right: absolute + relative stacked ('both' mode).

Name
Relative only
Absolute + relative
Aurora Chenlast month
Mateo Silvalast month
Priya Nairlast month
{ renderAs: 'datetime', renderAsOptions: { parseMode: 'iso-datetime', relativeTime: true, relativeDisplay: 'relative' } }
{ renderAs: 'datetime', renderAsOptions: { parseMode: 'iso-datetime', relativeTime: true, relativeDisplay: 'both'     } }

Format Presets​

short / medium / long / full presets applied to the same ISO datetime.

Name
short
medium
long
full
Aurora Chen
Mateo Silva
Priya Nair
{ renderAs: 'datetime', renderAsOptions: { parseMode: 'iso-datetime', formatPreset: 'short'  } }
{ renderAs: 'datetime', renderAsOptions: { parseMode: 'iso-datetime', formatPreset: 'medium' } }  // default
{ renderAs: 'datetime', renderAsOptions: { parseMode: 'iso-datetime', formatPreset: 'long'   } }
{ renderAs: 'datetime', renderAsOptions: { parseMode: 'iso-datetime', formatPreset: 'full'   } }  // includes timezone name

Options Reference​

OptionTypeDefaultEffect
parseModeTemporalParseModerequiredHow to parse the raw value.
localestring'en-US'BCP 47 locale tag.
timezonestring'local''local', 'utc', or IANA zone.
formatPreset'short' | 'medium' | 'long' | 'full''medium'Preset Intl option set. 'full' includes timezone name.
formatOptionsIntl.DateTimeFormatOptionsunsetFull Intl.DateTimeFormat options — merged over formatPreset.
showSecondsbooleanfalseInclude seconds component.
hour12booleanlocale defaultForce 12h or 24h.
relativeTimebooleanfalseUse Intl.RelativeTimeFormat instead of absolute formatting.
relativeDisplay'relative' | 'both''relative''relative': relative text only. 'both': absolute on top, relative below.
fallbackTextstring'Invalid'Text shown when parsing fails.
classNamestringunsetAdditional CSS class on the root element.

parseMode values​

ValueParses
'iso-datetime'ISO 8601 datetime strings
'epoch-ms'Unix timestamp in milliseconds
'epoch-sec'Unix timestamp in seconds
'iso-date'YYYY-MM-DD strings (time component becomes 00:00:00)
'any'Auto-detect

Caveats​

  • parseMode is required. Without it the renderer outputs fallbackText immediately.
  • Relative time thresholds: seconds < 60s, minutes < 60m, hours < 24h, days < 30d, months < 12m, then years. All computed via Intl.RelativeTimeFormat.
  • relativeTime uses the current wall clock at render time. The value is not live-updated — it reflects the time the component rendered.
  • formatPreset: 'full' adds timeZoneName: 'short' to the Intl options, which displays the timezone abbreviation (e.g. "UTC", "EST").
  • All options accept (entity) => value functions for per-row dynamic values.

See Also​