duration Field Type

type: 'duration' marks a field as an elapsed-time value. Pair it with renderAs: 'duration' and a unit that matches the source value's magnitude. Three output formats are available: clock (HH:MM:SS), humanized ("2 hours 3 minutes"), and decimal (61.25).

Core Examples

Clock Format

format: 'clock' renders duration as HH:MM:SS. Useful for timer-style displays and processing metrics.

Processing latency in seconds rendered as HH:MM:SS clock format.

Operation	Latency
Payroll Sync	01:01:01
Reserve Sweep	00:15:15
Invoice Clear	00:02:52

{
  key: 'latencySec',
  label: 'Latency',
  type: 'duration',
  renderAs: 'duration',
  renderAsOptions: { unit: 'sec', format: 'clock' },
}

Condition

Queue lag column only shown for rows where lag exceeds 10 seconds (Invoice Clear at 7.2s is hidden).

Operation	Latency	Queue Lag
Payroll Sync	1 hour 1 minute	48 seconds
Reserve Sweep	15 minutes 15 seconds	2 minutes
Invoice Clear	2 minutes 52 seconds

{
  key: 'queueLagMs',
  label: 'Queue Lag',
  type: 'duration',
  renderAs: 'duration',
  renderAsOptions: { unit: 'ms', format: 'humanized', precision: 1, showSign: false },
  condition: (entity) => entity.queueLagMs > 10000,
}

Field Options Reference

Option	Type	Default	Effect
key	string	required	Entity property to read the duration value from.
label	string	unset	Column header or card label.
type	'duration'	—	Marks the field as an elapsed-time value. Pair with renderAs: 'duration'.
renderAs	'duration'	unset	Required for formatted output. Without it, raw value renders as plain text.
condition	(entity) => boolean	unset	Hides the field for rows where the function returns false.
sortable	boolean	false	Enables column sorting. Sorts numerically when unit is set.
width	CSS length or number	unset	Sets column width in table mode.
align	'left', 'center', 'right'	'left'	Text alignment in table mode.

renderAsOptions for renderAs: 'duration'

unit is required — without it the field renders 'Invalid'. All other display options (format, humanizedUnits, precision, showSign, formatOptions, fallbackText) are documented on the duration Renderer page.

Caveats

• unit is required. Without it, the field renders 'Invalid'.
• format: 'humanized' with year or month units uses approximations: 1 year = 365 days, 1 month = 30 days. For calendar-accurate intervals, compute the display string in the host app and pass it as type: 'text'.
• showSign defaults to true — this prefixes all positive values with +. Set showSign: false if you don't want sign indicators on positive values.
• format: 'decimal' renders the value in the declared unit — a 3661-second value with unit: 'sec' and precision: 2 renders 3661.00, not 1.02 hours. Convert units in the host app or use humanized format for multi-unit breakdown.
• Table sorting on duration columns works numerically when unit is set and sortable: true.

See Also

• duration Renderer — full renderAsOptions reference
• Temporal Fields Guide — cross-type contracts, sorting behavior, best practices
• timestamp Field Type
• Item Config — item-level shape and layout contract
• Field Config