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

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 show the same comma style.

The Intl.DurationFormat object solves this problem elegantly. It’s part of ECMAScript’s core language specification - specifically the ECMAScript Internationalization API (ECMA-402). 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.

The duration object accepts multiple time units: 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:

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

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.


Trevor I. Lasn

Trevor I. Lasn

Building whiteheap.com and 0xinsider.com.



Related Articles

Check out these related articles that might be useful for you. They cover similar topics and provide additional insights.

JavaScript
5 min read

The Stage 2 pipeline operator passes a value through a chain of calls left to right, with % marking where it goes, instead of nesting h(g(f(x))).

Oct 29, 2024
Read article
JavaScript
5 min read

How to handle exact decimal calculations in JavaScript when floating-point precision isn't good enough

Nov 16, 2024
Read article
JavaScript
3 min read

Copy and paste text, images, and files using the new navigator.clipboard API

Dec 7, 2024
Read article
JavaScript
3 min read

x ??= y assigns y only when x is null or undefined, so 0, false and empty strings stay. How it differs from || and where it saves code.

Nov 5, 2024
Read article
JavaScript
4 min read

The 'with' statement is the only feature ever deprecated in JavaScript

Aug 22, 2024
Read article
JavaScript
4 min read

Understanding the new import attributes syntax and why we can't rely on file extensions alone

Nov 10, 2024
Read article
JavaScript
4 min read

Intermediate variables name each step of complex logic, and early returns handle failing cases first. A JavaScript authentication check, rewritten both ways.

Aug 30, 2024
Read article
JavaScript
6 min read

Closures are essential for creating functions that maintain state, without relying on global variables.

Sep 6, 2024
Read article
JavaScript
5 min read

scheduler.postTask() runs JavaScript at user-blocking, user-visible or background priority, giving finer control than setTimeout(0) over when work runs.

Nov 26, 2024
Read article

This article was originally published on https://www.trevorlasn.com/blog/intl-durationformat-javascript-time-durations-with-locale-support. It was written by a human and polished using grammar tools for clarity.