How do I Format a Date in JavaScript?

Matthew C.

The Problem

You have a Date object that you would like to display as a user-friendly string of text. How do you do this?

The Solution

The date object has multiple methods for creating a date string in different formats. The two main methods are Date.toLocaleDateString() and Intl.DateTimeFormat(). Both of these are used to return a formatted date string. The date is formatted for a specific language and time zone.

These methods have two arguments, locales and options, which allow specification of the language that has specific formatting and customizing that format. Both of these arguments are optional. If neither is supplied, the time zone and language of the user’s system will be used for formatting the date and the default values for the options will be used.

Two other methods are similar to Date.toLocaleDateString(): Date.toLocaleString() and Date.toLocaleTimeString(). Date.toLocaleString() has a similar formatted date string output to Date.toLocaleDateString(), except it adds the time if no options are passed. The Date.toLocaleTimeString() method only returns the time portion of the date.

You can use any of these methods to format a date. If you are formatting many dates, use Intl.DateTimeFormat(), as it allows you to create an Intl.DateTimeFormat object that you can format multiple times using the format() method. You only define the locales and options once.

const date = new Date(Date.UTC(2022, 10, 22, 9, 0, 0));
const date2 = new Date(Date.UTC(2022, 11, 22, 9, 0, 0));
const options = {
  weekday: "long", year: "numeric", month: "long", day: "numeric",
};

console.log(date.toLocaleDateString("en-ZA", options)); // Tuesday, 22 November 2022
console.log(date.toLocaleDateString("ko", options));
// 2022년 11월 22일 화요일

const intDateFormat = new Intl.DateTimeFormat("en-ZA", options);
console.log(intDateFormat.format(date)); // Tuesday, 22 November 2022
console.log(intDateFormat.format(date2)); // Thursday, 22 December 2022

The locales Argument

The first argument for the methods, locales, is a string representing the language, script, or region subtag, or an array of these strings. You can find a list of these strings in the IANA language subtag registry. This list is periodically updated and implementations may not always be up to date with the list. Some examples include:

• "en": English (language)

• "zh-Hans-CN": Chinese (language) written in simplified characters (script) as used in China (region)

The options Argument

The second argument, options, is an object that’s used to modify the output format. If it is undefined or not provided, default values are used for all properties. There are many properties available, which you can see in the Intl.DateTimeFormat() constructor. These include: dateStyle, timeStyle, calendar, dayPeriod, numberingSystem, timeZone, era, year, month, day, hour, minute, and second. Here’s an example formatted date that uses the dateStyle and timeStyle properties:

const date = new Date(Date.UTC(2022, 10, 22, 9, 0, 0));
const dtf = new Intl.DateTimeFormat("de-DE", { dateStyle: "short", timeStyle: "long" });
console.log(dtf.format(date)); // 22.11.22, 11:00:00 GMT+2