JavaScript date and time Formatting with Intl.DateFormat

Table of Contents

Intl Object in JavaScript

Intl ( internationalization )is an in-built Object in JavaScript for language-sensitive formatting. It includes constructors for formatting strings, lists, numbers, and dates and times. In this post, I am going to talk about JavaScript date and time formatting with Intl.DateTimeFormat() constructor.

Intl.DateTimeFormat()

Intl.DateTimeFormat() constructor creates an instance of Intl.DateTimeFormat. You can use this to apply formattings with its instance methods.

You can create an Intl.DateTimeFormat object in one of the following ways.

new Intl.DateTimeFormat();
new Intl.DateTimeFormat(locales);
new Intl.DateTimeFormat(locales, options);

or

Intl.DateTimeFormat();
Intl.DateTimeFormat(locales);
Intl.DateTimeFormat(locales, options);

As you can notice Intl.DateTimeFormat() takes a maximum of two parameters. These parameters are critical in applying language-sensitive formatting.

So, let’s talk about these parameters.

How to use the locales parameter

This a string of BCP 47 language subtags
You can also have an array of strings these strings
The string can also take Unicode extensions for number systems, calendars, and hour cycles.

let’s see some examples of using locale parameters.

First of all, we need to create an instance with Intl.DateTimeFormat();

Then, you can use one of the instance methods called format( date ) to apply formattings.

If you use Intl.DateTimeFormat(), without any parameters, the local system settings will be used. In my case, it is as follows.

const dateFormat = Intl.DateTimeFormat();
const today = dateFormat.format( Date.now() );
console.log( today  );

//Output: 1/18/2023

This default system is, perhaps, what many of us use. Note, that Intl.DateTimeFormat() returns only the date.

But, let’s say you need to output how a date is written in India. You can use Hindi or Tamil ( two major languages in India) subtags.

const dateFormat = Intl.DateTimeFormat('hi'); //hi for Hindi
// Intl.DateTimeFormat('ta'); ta for Tamil

const today = dateFormat.format( Date.now() );
console.log( today );
//Output: 1/18/2023

Bengali is another major language used in India. Let’s see how the date is written using Bengali.

const dateFormat = Intl.DateTimeFormat('bn');
const today = dateFormat.format( Date.now() );
console.log( today );

//output: ১৮/১/২০২৩

As you can see Bengali has a different number system. So, the output is produced using its unique number system.

Let’s see in Arabic

const dateFormat = Intl.DateTimeFormat('ar');
const today = dateFormat.format( Date.now() );
console.log( today );

//output: 18‏/1‏/2023    this is not an error. This is the real output 🙂

How to use the options parameter

The options parameter is another parameter that the Intl.DateTimeFormat() takes. This parameter is an object, and it can have one or more properties to format date and time. Some of the properties are dateStyle, timeStyle ,dayPeriod, timeZone, Hour12,hourCycle, year, month, day, hour, minute, and second.

It will make sense when the options parameter is used in combination with the locale parameter.

Lets’ see some examples.

dateStyle

I will use locale as ‘en_US’ and dateStyle as 'full‘

const dateFormat = new Intl.DateTimeFormat('en-US', { 
  dateStyle: 'full'
});
const date = dateFormat.format( Date.now() );
console.log( date );

The following table shows what it returns for the other values of dateStyle property.

dateStyle	output
‘full’	Wednesday, January 18, 2023
‘long’	January 18, 2023
‘medium’	Jan 18, 2023
‘short’	1/18/23

Now, I will give you a small exercise for you to experiment with.

Try and see what happens when you change the locale to ‘ar’, which stands for Arabic. See what output you get.

timeStyle

By default, Intl.DateFormat()returns only the date. But, we can control it by setting timeStyle property.

const dateFormat = new Intl.DateTimeFormat('en-US', { 
    timeStyle:'full'
});
const date = dateFormat.format( Date.now() );
console.log( date );

Let’s see what output you would get for all the values for this property

timeStyle	output
‘full’	12:20:33 PM Pacific Standard Time
‘long’	12:20:33 PM PST
‘medium’	12:20:33 PM
‘short’	12:20 PM

You can also use dateStyle and timeStyle properties together.

const dateFormat = new Intl.DateTimeFormat('en-US', { 
    dateStyle:'long',
    timeStyle:'short'
});
const date = dateFormat.format( Date.now() );
console.log( date );
//Output: January 18, 2023 at 7:39 PM

You can also use it with hourCycle, which is another property. hourCycle: 'h24' is for the 24-hour clock.

const dateFormat = new Intl.DateTimeFormat( 'en-US', {  
    hourCycle:'h24',
    timeStyle:'full',
});
const date = dateFormat.format( Date.now() );
console.log( date );
//Output : 19:37:19 Pacific Standard Time

However, you can not use some properties in combination with another property. For example, timeStyle can not be used with dayPeriod. This produces an error.

timeZone

Another property that you need frequently is timeZone. You can set it to receive a time at a different timeZone.

const dateFormat = new Intl.DateTimeFormat( 'en-US', {
   timeStyle:'full',
   timeZone:'Asia/Kolkata'
});
const date = dateFormat.format( Date.now() );
console.log( date );
//Output: 4:36:40 AM India Standard Time

More customization in date and time formatting

You can also add more customization for formatting dates and times with year, month, day, hour, minute, second and fractionalSecondDigits properties.

const dateFormat = new Intl.DateTimeFormat( 'en-US', {
    year:'2-digit',
    month:'long',
    day:'2-digit',
    hour:'numeric',
    minute:'2-digit',
    second:'2-digit',
    fractionalSecondDigits: '2'
});

const date = dateFormat.format( Date.now() );
console.log( date );

//Output: January 18, 23 at 3:21:58.73 PM

You can learn more about these properties at Mozilla Developer Network.

Conclusion

Date and Time formatting can be complex depending on your application. You need to do your own experiments with Intl.DateTimeFormat(). The best way I found is to play around with those two parameters. The instance methods of the Date object toLocaleDateString(), toLocaleString(), and toLocaleTimeString() also use these same parameters in a similar manner.

How to format JavaScript date and time with Intl.DateFormat