Skip to main content

timestamp Field Type

type: 'timestamp' marks a field as a machine-generated epoch timestamp — a numeric Unix value (seconds or milliseconds) or an ISO datetime string from a system log, audit trail, or event stream. Pair it with renderAs: 'timestamp' and the correct parseMode for the source format.

Core Examples​

epoch-sec and epoch-ms​

The two most common timestamp formats in backend systems. parseMode tells the renderer how to interpret the raw number.

Two timestamp columns from the same dataset — one in Unix seconds, one in Unix milliseconds. Both render identically with the correct parseMode.

Operation
Updated (epoch-sec)
Ingested (epoch-ms)
Payroll Sync
Reserve Sweep
Invoice Clear
// Unix seconds
{
  key: 'updatedAtEpochSec',
  label: 'Updated',
  type: 'timestamp',
  renderAs: 'timestamp',
  renderAsOptions: { parseMode: 'epoch-sec', locale: 'en-US', timezone: 'utc', formatPreset: 'medium' },
}

// Unix milliseconds
{
  key: 'ingestedAtEpochMs',
  label: 'Ingested',
  type: 'timestamp',
  renderAs: 'timestamp',
  renderAsOptions: { parseMode: 'epoch-ms', locale: 'en-US', timezone: 'utc', formatPreset: 'medium' },
}

Sorting​

Timestamps sort chronologically in table mode when parseMode is declared and sortable: true is set.

Table pre-sorted descending by epoch-sec timestamp. Click the column header to toggle sort direction.

Operation
Updated
Invoice Clear
Reserve Sweep
Payroll Sync
{
  key: 'updatedAtEpochSec',
  label: 'Updated',
  type: 'timestamp',
  renderAs: 'timestamp',
  sortable: true,
  renderAsOptions: { parseMode: 'epoch-sec', locale: 'en-US', timezone: 'utc', formatPreset: 'medium' },
}

Field Options Reference​

OptionTypeDefaultEffect
keystringrequiredEntity property to read the timestamp value from.
labelstringunsetColumn header or card label.
type'timestamp'—Marks the field as a machine-generated epoch value. Pair with renderAs: 'timestamp'.
renderAs'timestamp'unsetRequired for formatted output. Without it, raw value renders as plain text.
condition(entity) => booleanunsetHides the field for rows where the function returns false.
sortablebooleanfalseEnables column sorting. Sorts chronologically when parseMode is set.
widthCSS length or numberunsetSets column width in table mode.
align'left', 'center', 'right''left'Text alignment in table mode.

renderAsOptions for renderAs: 'timestamp'​

parseMode is required — without it the field renders 'Invalid'. All other display options (formatPreset, locale, timezone, relativeTime, showSeconds, hour12, formatOptions, etc.) are documented on the timestamp Renderer page.

Caveats​

  • parseMode is required. Without it, the field renders 'Invalid'.
  • epoch-sec and epoch-ms are the two most common choices. Mixing them (e.g. passing milliseconds with epoch-sec) produces a date far in the future — verify your source format.
  • type: 'timestamp' and type: 'datetime' share the same renderer internally (renderTemporal with kind: 'datetime'). The distinction is semantic: timestamp signals a machine-generated epoch value; datetime signals a human-authored date+time.
  • parseMode: 'any' attempts multiple formats in order. Use it only when the source format is genuinely unknown — it is less reliable than explicit modes.

Why timestamp vs datetime?​

Both accept epoch values with parseMode: 'epoch-ms' or 'epoch-sec' and render identically. The distinction is semantic:

  • type: 'timestamp' — the value comes from a system clock, audit log, or event stream. The epoch integer is the primary form.
  • type: 'datetime' — the value is a human-readable ISO string authored to represent a specific point in time.

Using the correct type communicates intent clearly and will matter for future features like inline editing (timestamp fields would get a read-only display; datetime fields might get a datetime picker).

See Also​