---
title: "Intl.DurationFormat: Format Durations with Locale Support"
description: "Stop writing manual duration formatting code. Instead, leverage the new powerful Intl.DurationFormat API for internationalized time displays"
canonical: "https://www.trevorlasn.com/blog/intl-durationformat-javascript-time-durations-with-locale-support"
author: "Trevor I. Lasn"
published: "2025-03-13"
last-updated: "2026-11-08"
topics: ["JavaScript"]
---

# Intl.DurationFormat: Format Durations with Locale Support

Stop writing manual duration formatting code. Instead, leverage the new powerful Intl.DurationFormat API for internationalized time displays

By Trevor I. Lasn · Published 2025-03-13 · Updated 2026-11-08 · https://www.trevorlasn.com/blog/intl-durationformat-javascript-time-durations-with-locale-support

Time durations appear everywhere - video players showing remaining time, fitness apps tracking workout lengths, or project management tools measuring task completion time. Formatting these durations consistently across different locales has traditionally required custom code or external libraries.

## Update: Corrected Example Outputs

November 8, 2026: Corrected four sample outputs to what `Intl.DurationFormat` prints in Node.js 26.13 (ICU 79.1). English long style separates units with commas and adds no "and", so the result is "2 hours, 30 minutes", and Japanese puts spaces between numbers and units: "1 時間 30 分". [MDN's examples](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DurationFormat/format) show the same comma style.

[Browser support for `intl-duration-format` on webstatus.dev](https://webstatus.dev/features/intl-duration-format)

The `Intl.DurationFormat` object solves this problem elegantly. It's part of ECMAScript's core language specification - specifically the ECMAScript Internationalization API [(ECMA-402)](https://tc39.es/ecma402/#sec-intl-durationformat-constructor). This makes it a native JavaScript feature rather than a web browser API, though browser implementation determines its availability.

At its core, `Intl.DurationFormat` takes a duration object containing time units and formats it according to locale-specific rules. The basic usage is straightforward.

```js title="JavaScript"
const duration = { hours: 2, minutes: 30 };
const formatter = new Intl.DurationFormat('en-US', { style: 'long' });
const result = formatter.format(duration);
// Output: "2 hours, 30 minutes"
```

The duration object accepts multiple [time units](https://tc39.es/proposal-intl-duration-format/#sec-duration-records): **years**, **months, weeks**, **days**, **hours**, **minutes**, **seconds**, **milliseconds**, **microseconds**,  and **nanoseconds**. This flexibility allows you to represent any time span from nanoseconds to centuries.

The locale parameter determines how the duration appears based on language and regional conventions. English separates the units with commas, while French joins them with "et" - these nuances happen automatically:

```js title="JavaScript"
const duration = { hours: 1, minutes: 30 };

// English formatting
new Intl.DurationFormat('en-US', { style: 'long' }).format(duration);
// "1 hour, 30 minutes"

// French formatting
new Intl.DurationFormat('fr-FR', { style: 'long' }).format(duration);
// "1 heure et 30 minutes"

// Japanese formatting
new Intl.DurationFormat('ja-JP', { style: 'long' }).format(duration);
// "1 時間 30 分"
```

The output style can be customized through the options parameter. Three primary styles exist: **'long'**, **'short'**, and **'narrow'**. Each provides progressively more compact representations:

```js title="JavaScript"
const duration = { hours: 2, minutes: 45, seconds: 30 };

// Long format - fully spelled out
new Intl.DurationFormat('en-US', { style: 'long' }).format(duration);
// "2 hours, 45 minutes, 30 seconds"

// Short format - abbreviated but clear
new Intl.DurationFormat('en-US', { style: 'short' }).format(duration);
// "2 hr, 45 min, 30 sec"

// Narrow format - most compact
new Intl.DurationFormat('en-US', { style: 'narrow' }).format(duration);
// "2h 45m 30s"
```

To wrap up this article, here's a final example with all the possible duration units. It demonstrates the full range of time units and how `Intl.DurationFormat` handles them.

```js title="JavaScript"
// Full duration object using all possible time units
const fullDuration = {
  years: 2,
  months: 3,
  weeks: 1,
  days: 4,
  hours: 12,
  minutes: 30,
  seconds: 15,
  milliseconds: 300,
  microseconds: 750,
  nanoseconds: 500
};

const formatter = style => new Intl.DurationFormat('en-US', { style });

// long format - fully spelled out
const formattedLongDuration = formatter('long').format(fullDuration);
console.log(formattedLongDuration);
// Output: "2 years, 3 months, 1 week, 4 days, 12 hours, 30 minutes, 15 seconds, 300 milliseconds, 750 microseconds, 500 nanoseconds"

// short format - abbreviated but clear
const formattedShortDuration = formatter('short').format(fullDuration);
console.log(formattedShortDuration);
// Output: "2 yrs, 3 mths, 1 wk, 4 days, 12 hr, 30 min, 15 sec, 300 ms, 750 μs, 500 ns"

// narrow format - most compact
const formattedNarrowDuration = formatter('narrow').format(fullDuration);
console.log(formattedNarrowDuration);
// Output: "2y 3m 1w 4d 12h 30m 15s 300ms 750μs 500ns"
```
