toLocaleDateString in JavaScript – For Humans

Have you ever wanted to add a date format that customizes itself based on the timezone? In JavaScript, one such function automatically customizes the date in a locale-sensitive manner, toLocaleDateString().

Table of Contents

• What is the toLocaleDateString() Method?
• toLocaleDateString() Method Parameters
  • Using locales
  • Using options
• More Examples
• Wrapping Up

🔥 Learn JavaScript Programming – Beginner Friendly!
🔨 JavaScript Basics
👉 JavaScript alert()
👉 Difference between Let and Const
🔸 JavaScript Arrays
👉 JavaScript Array Filter
👉 JavaScript Array Find
👉 JavaScript forEach (Arrays)
👉 JavaScript Slice (Arrays)
👉 JavaScript Spread Operator
🔸 JavaScript Strings
👉 JavaScript Slice(Strings)
👉 JavaScript Includes
🌐 Web Development with JavaScript
👉 Store User Input in a variable with JS
⚙️ JavaScript Specifics
👉 Sorting Numbers in JS
👉 JavaScript Fetch API
👉 toLocaleDateString in JavaScript

What is the toLocaleDateString() Method?

The toLocaleDateString() method returns a string representation of the date format in the user’s timezone.

The syntax of the toLocaleDateString() method is:

Syntax

date.toLocaleDateString()

Code language: JavaScript (javascript)

Example

<script>
   const dateObj = new Date();
   document.write(dateObj.toLocaleDateString());
</script>

Code language: JavaScript (javascript)

Output

3/24/2022

Code language: Bash (bash)

toLocaleDateString() Method Parameters

The toLocaleDateString() method also comes with two parameters:

• locales
• options

The locales and options arguments allow programs to customize the function’s behavior and specify which language’s formatting conventions should be utilized.

Syntax

dateObj.toLocaleDateString( [locales][, options])

Code language: JavaScript (javascript)

• The locales option specifies how the date will be displayed in format or language. This optional parameter allows the programmer to choose the date’s display formats.
• The options parameter specifies the format in which the date will be shown.

Using locales

The locales argument specifies the format or language in which the date format should be displayed.

The locales parameter includes a BCP 47 language tag, which comprises one or more subtags such as language, region, variant, and script subtags.

The locales consist of the following parts:

nu

The nu refers to the numbering system of the locale at which the date format will appear. The possible values are “arab”, “arabext”, “bali”, “laoo”, “latn”, “limb”, “mlym”, “mong”,”beng”, “deva”, “fullwide”, “gujr”, “guru”, “hanidec”, “khmr”, “knda”, “mymr”, “orya”, “tamldec”, “telu”, “thai”, “tibt”.

ca

The ca refers to the calendar format of the local timezone. The possible values are: “buddhist”, “chinese”, “hebrew”, “indian”, “islamic”, “islamicc”, “iso8601”, “japanese”, “coptic”, “ethioaa”, “ethiopic”, “gregory”, “persian”, “roc”.

Example Using Locales

const  event = new  Date(Date.UTC(2022, 02, 24, 3, 0, 0));

console.log(event.toLocaleDateString('en-US'));
//displays the date in US format

console.log(event.toLocaleDateString('ko-KR'));
//displays the date in Korean format

console.log(event.toLocaleDateString('fa-IR'));
//displays the date in Persian Format

console.log(event.toLocaleDateString('ja-JP-u-ca-japanese'));
//displays the date in Japanese format, where 2022 is the 4th year in the Reiwa era.
Code language: JavaScript (javascript)

Output

3/24/2022

2022. 3. 24.

۱۴۰۱/۱/۴

4/3/24

Code language: Bash (bash)

Using options

The programmer can specify various options to display the date using the options parameter. The properties listed below can be utilized in the options parameter:

localeMatcher

The localMatcher defines the format in which the date will be displayed. Possible values are:

• “lookup”
• “best fit”.

The default value is the best fit.

timeZone

Using the timeZone, the date will be displayed in the time zone specified. The default time zone is that of the runtime.

The only value implementations must recognize ‘UTC’. The time zone names from the IANA time zone database, such as “Asia/Shanghai,” “Asia/Kolkata,” and “America/New York,” might be recognized by implementations.

formatMatcher

The formatMatcher allows the programmer to choose which format the date should be displayed.

Possible values are:

• “basic”
• “best fit”, is the default value.

This method’s implementations must offer at least the following subsets of date formatting properties:

• weekday, year, month, day, hour, minute, second
• weekday, year, month, day
• year, month, day
• year, month
• month, day
• hour, minute, second
• hour, minute

Other subsets may well be supported, and requests will be compared to all subset-representation combinations to identify the best match.

Weekday

The weekday option is used to specify the format in which the day of the week should be shown.

The following are examples of possible values:

• “long”1(e.g., Monday)
• “short” (e.g., Mon)
• “narrow” (e.g., M). 2 weekdays may be the same narrow style for some locales (e.g. Tuesday and Thursday are both T )

era

The era represents the period in which the current date occurs. The following are examples of possible values:

• “long” (e.g., Anno Domini)
• “short” (e.g., AD)
• “narrow” (e.g., A)

year

The year indicates the format in which the year should be applied. The following are examples of possible values:

• “numeric” (e.g., 2020)
• “2-digit” (e.g., 20)

month

You can specify how the month should be displayed using the month option. The following are examples of possible values:

• “numeric” (e.g., 1)
• “2-digit” (e.g., 01)
• “long” (e.g., January)
• “short” (e.g., Jan)
• “narrow” (e.g., J). Two months may have the same narrow style for some locales (e.g. March and May’s narrow style are both M).

day

The day option allows you to specify the format in which the day should be expressed. The following are examples of possible values:

• “numeric” (e.g., 2)
• “2-digit” (e.g., 02)

hour

The hour option is used to represent the hour. The following are examples of possible values:

• “numeric”
• “2-digit”.

minute

The minute option is used to represent its minutes. Possible values include:

• “numeric”
• “2-digit”.

second

The second is the representation of the second. Possible values are:

• “numeric”
• “2-digit”.

timeZoneName

The timeZoneName is the representation of the time zone name. Possible values are:

• “long” (e.g., Pacific Standard Time, Eastern Standard Time)
• “short” (e.g., PST, EST)

Example Using Options

In the following example we are using the options to display dates in the specified time zones and languages:

const  event = new  Date(Date.UTC(2022, 02, 24, 3, 0, 0));

const  options = { weekday:  'long',
year:  'numeric',
month:  'long',
day:  'numeric' };

console.log(event.toLocaleDateString('de-DE', options));
// displays the date in German

console.log(event.toLocaleDateString('ar-EG', options));
//displays the date in Arabic

console.log(event.toLocaleDateString('ja-JP', options));
//displays the date in Japanese
Code language: JavaScript (javascript)

Output

Donnerstag, 24. März 2022

الخميس، ٢٤ مارس ٢٠٢٢

2022年3月24日木曜日

Code language: Bash (bash)

More Examples

With the types of parameters and functions we have seen, now let’s look at some examples to understand more clearly how they can be used:

Example

const  date = new  Date(Date.UTC(2022, 02, 24, 3, 0, 0));

const  options = { weekday:  'short',
year:  'numeric',
month:  'long',
day:  'numeric' };

console.log(date.toLocaleDateString('ja-JP-u-ca-japanese'));
//displays the Japanese date format

console.log(date.toLocaleDateString('ja-JP', options));
//displays the date format in Japanese along with the era name.

options.timeZone = 'UTC';
options.timeZoneName = 'short';
options.era = 'long';

//to display the era
console.log(date.toLocaleDateString('en-US', options));

Code language: JavaScript (javascript)

Output

4/3/24

2022年3月24日(木)

Thu, March 24, 2022 Anno Domini, UTC

Code language: Bash (bash)

Wrapping Up

We hope you now know how to utilize the toLocaleDateString() method and its parameters in a program and how they can assist you in setting locale-sensitive dates. Try out the given examples and alter the code with other options and properties to get a more firm grip on this concept.