You may not need a library for that: Dates/Times
Handling dates and times in a user-friendly way can be a daunting task due to the variety of date formats and time zones used around the globe, and due to the Date class being hard to work with. Usually, we would reach for a library to accomplish this, like moment.js or day.js. However, depending on what you’re doing with Dates and Times, you probably don’t need a library where a JavaScript API will do.
Note: TC39 is working on Temporal, a new Date/Time API. Read more about it on the Igalia blog. It’s not ready for production use yet, but it’s coming soon!
JavaScript provides a powerful internationalization API that includes Intl.DateTimeFormat, which is designed to enable language-sensitive date and time formatting.
What is Intl.DateTimeFormat?
Intl.DateTimeFormat is a constructor part of the ECMAScript Internationalization API that enables developers to format date and time values according to the locale and formatting options provided. This functionality is crucial for creating applications that can display dates and times in a way that is familiar to users from different parts of the world.
How to Use Intl.DateTimeFormat
To use Intl.DateTimeFormat, you need to create a new instance of it and then call its format method to get a string with the formatted date or time.
Here’s the basic syntax:
const date = new Date();
let formatter = new Intl.DateTimeFormat(locale, options);
let formattedDate = formatter.format(date);Let’s break this down a bit:
We first create a new object called formatter that will format dates for us based on the arguments (locale and options) we pass in. We then use the .format method on the formatter object to actually turn the date or time into something we want. What about the arguments?
- locale is a string with a BCP 47 language tag, or an array of such strings, that represents the locale to use. If you omit this argument, the default locale of the JavaScript runtime will be used.
- options is an optional object that provides additional formatting options like time zone, hour cycle, etc.
- date is the Date object that you want to format.
Now that we know the basics let’s take a look at some examples to show us how to actually use this in an application.
Date/Time Examples
Basic Date Formatting
Most of time you just need some basic Date Formatting in the users local format. To accomplish this you can do the following:
// To format a date in a user's local format:
let date = new Date();
let formatter = new Intl.DateTimeFormat();
console.log(formatter.format(date)); // Output will vary based on user's localeSpecifying a Locale
Let’s say we wanted our output to be for a certain locale. This is pretty easy too. Let’s see:
// To format a date for a specific locale, such as British English:
const britishLocale = 'en-GB';
let date = new Date();
let formatter = new Intl.DateTimeFormat(britishLocale);
console.log(formatter.format(date)); // Output: 23/03/2024Using Options
Many times when we are using dates, we want more than just displaying the Date in the user’s locale. We also want to change the way the date actually looks.
For example, we may just want to display only the year and month. To do this we can do the following:
let date = new Date();
let options = { year: 'numeric', month: 'long' };
let formatter = new Intl.DateTimeFormat('en-US', options);
console.log(formatter.format(date)); // Output: March 2024Time Formatting
I can already hear you saying “But what about time formatting?!?” The DateTimeFormat object can handle that too. To format a time with a 24-hour clock and include the time zone you can do the following:
let date = new Date();
let options = { hour: '2-digit', minute: '2-digit', timeZoneName: 'short' };
let formatter = new Intl.DateTimeFormat('en-US', options);
console.log(formatter.format(date)); // Output: 13:00 PM PSTSometimes you may be handed a Unix timestamp, it works with that as well.
The Unix time stamp is a way to track time as a running total of seconds. This count starts at the Unix Epoch on January 1st, 1970 at UTC. Therefore, the unix time stamp is merely the number of seconds between a particular date and the Unix Epoch.
const date = new Date(Date.UTC(2023, 11, 20, 3)).getTime(); // unix timestamp
const options = { dateStyle: 'full', timeStyle: 'long' }
// Specify date and time format using "style" options (i.e. full, long, medium, short)
console.log(new Intl.DateTimeFormat('en-US', options).format(date));
// Tuesday, December 19, 2023 at 10:00:00 PM EST
// if you omit the dateStyle it will assume you don't want the date
const options = {timeStyle: 'long' }
// Specify date and time format using "style" options (i.e. full, long, medium, short)
console.log(new Intl.DateTimeFormat('en-US', options).format(date));
// 10:00:00 PM ESTFormatting with Different Calendars
Sometimes you may want to format a date using a different calendar system, such as the Japanese calendar. To do that you can do the following:
let date = new Date();
let options = { calendar: 'japanese', year: 'numeric', month: 'long', day: 'numeric' };
let formatter = new Intl.DateTimeFormat('ja-JP', options);
console.log(formatter.format(date)); // Output: 令和6年3月23日Handling Multiple Locales
There are times when you need to handle multiple locales, the Intl.DateTimeFormat object can be provided with an array of locale strings. The formatter will then use the first locale it can successfully apply.
let date = new Date();
let options = { year: 'numeric', month: 'long', day: 'numeric' };
let locales = ['de-DE', 'fr-FR', 'ja-JP'];
let formatter = new Intl.DateTimeFormat(locales, options);
console.log(formatter.format(date));
// The output format will depend on the locales provided and the browser's ability to apply them.Conclusion
The Intl.DateTimeFormat object is a versatile and powerful tool in JavaScript that allows developers to format dates and times in a locale-sensitive manner.
Although the Date object makes dates hard to work with, the built in DateTimeFormat object can make it easier to work with Dates and Times in JavaScript. So the next time you need to work with Dates or Times in JavaScript, you may not need a library for that.
