How to Parse ISO 8601 Durations with JavaScript Temporal API

A practical guide for developers

1. The Challenge of ISO 8601 Durations in JavaScript

While JavaScript's built-in Date object has been the standard for handling dates and times, it doesn't have a native way to parse ISO 8601 duration strings like P1Y2M3DT4H5M6S. This can be a challenge when you're working with APIs or data sources that use this standard format.

Fortunately, the new Temporal API provides a modern and comprehensive solution. This guide will walk you through how to use it to handle ISO 8601 duration strings.

Browser Compatibility Note: As of late 2025, the Temporal API is a very new feature and is not yet supported in all browsers. For production applications, you may need to use a polyfill. Always check the latest support status on a site like Can I Use... before implementing.

2. Getting Started: Using Temporal.Duration.from()

The core function you'll use is Temporal.Duration.from(). This static method takes an ISO 8601 duration string as input and returns a Temporal.Duration object that provides access to all the duration components.

Here's a simple example:

// A duration of 1 day, 2 hours, and 30 minutes
const durationString = "P1DT2H30M";

// Parse the duration
const duration = Temporal.Duration.from(durationString);

console.log(duration.days);    // 1
console.log(duration.hours);   // 2
console.log(duration.minutes); // 30
console.log(duration.seconds); // 0

// The object is a Temporal.Duration
console.log(duration instanceof Temporal.Duration); // true

// You can also get the total duration in a specific unit
console.log(duration.total({ unit: "minutes" })); // 1530 (1 day + 2.5 hours in minutes)

3. Handling Years and Months

The Temporal API handles years and months correctly, unlike traditional JavaScript date handling. When a duration string contains years or months, the Temporal.Duration object preserves these components separately, allowing for proper date arithmetic.

// A duration of 1 year and 6 months
const durationString = "P1Y6M";

// Parse the duration
const duration = Temporal.Duration.from(durationString);

console.log(duration.years);  // 1
console.log(duration.months); // 6
console.log(duration.days);   // 0
console.log(duration.hours);  // 0

// The object is a Temporal.Duration
console.log(duration instanceof Temporal.Duration); // true

// You can access the components directly
console.log(`Years: ${duration.years}, Months: ${duration.months}`);
// Output: Years: 1, Months: 6

This object can then be added to a Temporal.PlainDate or Temporal.PlainDateTime object to perform date arithmetic correctly, accounting for varying month lengths and leap years.

4. Creating an ISO 8601 String from Components

The Temporal API also makes it easy to build a duration object from individual components and then convert it into a valid ISO 8601 string using the .toString() method.

// Create a duration of 5 hours, 10 minutes, and 20 seconds
const duration = new Temporal.Duration(0, 0, 0, 0, 5, 10, 20);
// Convert it back to an ISO 8601 string
const durationString = duration.toString();
console.log(durationString);
// Output: PT5H10M20S

5. Next Steps and Resources

While the Temporal API is the perfect tool for handling durations within a JavaScript application, sometimes you need a quick way to validate a string or understand the format itself. For that, we have two great resources: