Formatting

Introduction

Intl.DurationFormat turns a duration record like { hours: 1, minutes: 30 } into locale-aware text such as "1 hr, 30 min".

This sheet covers its styles, per-unit options, and output methods.

Duration records

const duration = { hours: 1, minutes: 30 }

new Intl.DurationFormat('en-US').format(duration)
// → '1 hr, 30 min'

Pass a plain object, not a Date or a millisecond count. The ten fields (years through nanoseconds) are optional, but at least one is required; values must be integers that share the same sign.

See: DurationFormat() constructor (developer.mozilla.org)

Styles

const duration = { hours: 1, minutes: 30 }
const format = style =>
  new Intl.DurationFormat('en-US', { style })
    .format(duration)

format('long')    // → '1 hour, 30 minutes'
format('short')   // → '1 hr, 30 min'
format('narrow')  // → '1h 30m'
format('digital') // → '1:30:00'

'short' is the default. 'digital' renders h:mm:ss, so seconds always appear; date units stay in prose, so { days: 2, hours: 3 } becomes '2 days, 3:00:00'.

See: style (developer.mozilla.org)

Locales

const duration = { hours: 1, minutes: 30 }
const format = locale =>
  new Intl.DurationFormat(locale, { style: 'long' })
    .format(duration)

format('en-US') // → '1 hour, 30 minutes'
format('de-DE') // → '1 Stunde, 30 Minuten'
format('ja-JP') // → '1 時間 30 分'

Word order, plural forms, and separators come from the locale. Output varies between ICU versions and engines, so never compare it to hardcoded strings.

See: Intl.DurationFormat (developer.mozilla.org)

Options

Per-unit styles

const duration = { hours: 1, minutes: 46, seconds: 40 }
const df = new Intl.DurationFormat('en', {
  style: 'digital',
  hours: 'long'
})

df.format(duration)
// → '1 hour, 46:40'

Option values

OptionValues
style'long', 'short', 'narrow', 'digital'
years–days'long', 'short', 'narrow'
hours–secondsthe above, plus 'numeric', '2-digit'
milliseconds–nanosecondsthe above, minus '2-digit'
…Display'always', 'auto'
fractionalDigits0 to 9

Per-unit styles default to style; under 'digital', the date units fall back to 'short'. Setting a unit's style makes it display even at zero unless its …Display is 'auto'.

See: DurationFormat() constructor (developer.mozilla.org)

Zero values

const df = new Intl.DurationFormat('en-US', {
  hours: 'long',
  hoursDisplay: 'always'
})

df.format({ minutes: 45 })
// → '0 hours, 45 min'

Zero-valued units are hidden by default. 'always' keeps one on screen, which stops columns and timers from jumping as values change.

See: Hide zero-value fields (github.com)

Fractional seconds

const duration = { seconds: 12, milliseconds: 345 }
const format = digits =>
  new Intl.DurationFormat('en', {
    style: 'digital',
    fractionalDigits: digits
  }).format(duration)

format()  // → '0:00:12.345'
format(2) // → '0:00:12.34'
format(5) // → '0:00:12.34500'

Digits are truncated toward zero, not rounded, and short values are padded with trailing zeros. Omit fractionalDigits to show as many digits as the input needs, up to nine.

See: Display fractional values (github.com)

Reading output

formatToParts

const parts = new Intl.DurationFormat('en-US', {
  style: 'long'
}).formatToParts({ hours: 1, minutes: 30 })

parts.map(p => `${p.type}: ${p.value}`)
// → ['integer: 1', 'literal: ', 'unit: hour',
//    'literal: , ', 'integer: 30', 'literal: ',
//    'unit: minutes']

Numbers arrive as integer (or decimal and fraction), separators as literal, and unit names as unit, so each piece can be styled on its own.

See: formatToParts() (developer.mozilla.org)

resolvedOptions

const df = new Intl.DurationFormat('de-DE', {
  style: 'narrow'
})
const { locale, style, hours } = df.resolvedOptions()

// locale: 'de-DE'
// style: 'narrow'
// hours: 'narrow'

resolvedOptions() reports the locale and every unit style after defaults are applied, including the …Display values.

See: resolvedOptions() (developer.mozilla.org)

Support

Browser support

RuntimeMinimum version
Chrome, Edge129
Firefox136
Safari16.4
Node.js23
Deno1.46
Bun1.0.3

The proposal reached Stage 4 in December 2024. Runtimes ship it with their bundled ICU data, so older versions have no Intl.DurationFormat at all.

See: Browser compatibility (developer.mozilla.org)

Feature detection

const formatter = 'DurationFormat' in Intl
  ? new Intl.DurationFormat('en-US')
  : null

Check for the constructor before using it, and load the FormatJS polyfill where it is missing.

See: FormatJS polyfill (formatjs.github.io)

Points in time

new Intl.RelativeTimeFormat('en-US')
  .format(-3, 'days')
// → '3 days ago'

Single quantities

new Intl.NumberFormat('en-US', {
  style: 'unit',
  unit: 'hour',
  unitDisplay: 'long'
}).format(2)
// → '2 hours'

Use Intl.DurationFormat for elapsed lengths, Intl.RelativeTimeFormat for points in time, and a unit Intl.NumberFormat for one standalone quantity.

See: Intl.RelativeTimeFormat (developer.mozilla.org)

0 Comments for this cheatsheet. Write yours!